Miden API Doc

## Sections
• [Get Started](https://docs.miden.co/getting-started.md): Overview The API documentation is intended for developers and technical teams to seamlessly integrate Miden’s financial infrastructure solutions into their applications and business processes. It provides the resources required to implement and manage products such as Cards, Business Accounts, Payment Gateway, Wallet as a Service (WaaS), Collections, Transfers, and webhook-driven financial workflows. Card Issuance: Our API allows businesses to issue virtual credit cards to their employees, vendors, or retail customers. It allows businesses to streamline the process of issuing cards, manage spending, and track transactions. The API documentation provides information on how to integrate our virtual card issuing system into a business's existing systems and outlines the features and functionalities of the API, including card creation, management, and reporting. It also provides technical specifications, such as API requests, responses, and authentication processes. Business Accounts Our Business Accounts API enables businesses to create and manage financial accounts programmatically. It provides access to features such as account management, transfers, collections, payouts, transaction monitoring, and webhook notifications. The API documentation outlines the available endpoints, authentication methods, request and response formats, and integration workflows required to operate business accounts securely and efficiently. Accruals & Disbursements Our Payment Gateway API allows businesses to accept and manage payments across multiple payment channels, including cards and virtual accounts. It supports payment collections, invoice management, transaction verification, and real-time webhook notifications. The API documentation provides integration guidelines, endpoint specifications, authentication requirements, and transaction processing workflows. Wallet as a Service (WaaS) Our Wallet as a Service (WaaS) API enables businesses to build and manage digital wallet solutions for their users. It supports wallet creation, balance management, transfers, deposits, withdrawals, and real-time transaction monitoring. The API documentation includes details on authentication, API endpoints, request and response structures, and wallet transaction workflows. Authentication/Authorization: To access any of the resources on the BaseUrl/api/v1/ , the client has to pass pre-defined headers for authentication and authorization. See Authentication process below: a. Reference b. Signature c. UniqueKey d. MidenAuthorization e. Authorization The API is secure and only authorized clients can consume the service. There is a clientId , clientSecret and uniqueKey assigned to every client for authentication and authorization. See below required headers how to derive headers. How to derive Headers: Part of every payload will be authentication and authorization headers and they are: a. Reference: The reference is a maximum 30-character string generated by the client and has to be unique for every request. e.g. 1232222Ehsj12345663 b. Signature: The signature is a more complex computation used for authentication. It is a combination of the Http verb, encoded url, client generated reference, client id, and client secrete. All will be hashed and encoded with base 64. See example below: $encodeUrl = urlencode($url); $baseStringToBeSigned = $method . "&" . $encodeUrl . "&" . $reference. "&". $clientId . "&" . $secret; $sign = Base64Encode(SHA1($baseStringToBeSigned)); For more details on how to generate signature, see here . c. UniqueKey: This is generated and shared as part of the client on-boarding process. d. MidenAuthorization: This is a combination of miden auth and base64 encoded client Id. E.g. MidenAuthorization = "MidenAuth " . Base64Encode ($clientId); note: "MidenAuth " is a fixed string that needs to be concatenated with the Base64-encoded value of _clientId_ e. Authorization: Authorization is the bearer token gotten from get token endpoint. This is required for all transactions. $token = token from identity get token login (get token url => https://sandbox-identityserver.midencards.io/connect/token ) Sample curl request: JSON curl --location --request POST 'https://sandbox-identityserver.midencards.io/connect/token --header 'Content-Type: application/x-www-form-urlencoded' --header 'Authorization: Basic REVGQVVMVE9SR0FOSVpBVElPTkFCRDc4OTNBMTYzMDRDRTVBNEM4RDQ2MjhDQzAwQkZCOjR6TC0hX2dLcTA1Q2VIdU8hTG4yTTk3QG4kcEAhQQ==' --data-urlencode 'grant_type=client_credentials' --data-urlencode 'scope=CardAPIs' BaseUrl : https://sandbox-api.midencards.io/miden Snippet for Generating Signature in PHP StartFragment JSON function nonce() { return substr(str_shuffle(MD5(microtime())), 0, 20); } function Base64Encode($value): string { return base64_encode($value); } function Base64Decode($value): bool|string { return base64_decode($value); } function SHA256($signaturecipher): bool|string { return hash("sha256",$signaturecipher); } function SHA1Here($signatureCipher): string { return sha1($signatureCipher, false); } EndFragment JSON $url = "full url of the request"; $encodeUrl = urlencode($url); $reference = nonce(); $clientId = "client Id generated during application creation"; $clientSecret = "generated during application creation"; $method = "Http method of the request"; $baseStringToBeSigned = $method . "&" . $encodeUrl . "&" . $reference. "&". $clientId . "&" . $clientSecret; $signature = Base64Encode(SHA1Here($baseStringToBeSigned));
• [Get Access Token](https://docs.miden.co/authentication/get-access-token.md): Overview Miden uses the OAuth 2.0 client credentials flow for API authentication. To call any protected endpoint, exchange your client_id and client_secret for a short-lived Bearer token, then include that token in the Authorization header of every subsequent request. Request an access token To obtain an access token, send a POST request to the token endpoint using Basic Authentication. Your Client ID and Client Secret must be Base64 encoded and included in the Authorization header. Token URL (sandbox) POST https://sandbox-identityserver.midencards.io/connect/token Authentication method The endpoint uses Basic Authentication: Field Value Username Client ID Password Client Secret How to get your API credentials 1 Register Complete your Sign up and onboarding process, with the registration link sent to the email address of your administrator. 2 Login After Onboarding, login to your account using your email address, password and 2fa Token. 3 Go to ‘Settings’ page Next, click on the ‘Settings’ icon at the top-right corner of your dashboard page 4 Navigate to “Developer” page From your Settings page, click on ‘Developer’ to navigate to the page 5 Fetch API credentials Finally, fetch your api credentials from your developer page The credentials must be encoded and passed in the Authorization header Authorization: Basic base64(client_id:client_secret) Ensure you have obtained your unique Client ID and Client Secret from your dashboard before using this endpoint. Replace {{tokenURL}} with the actual endpoint URL in your environment. Once you have the access_token, include it as a Bearer token in the Authorization header of every subsequent API request: Authorization: Bearer <access_token> For production credentials and endpoints, contact your account manager or onboarding team. Headers Field Value Content-Type application/x-www-form-urlencoded E xample Request C# using System; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using System.Text.Json; using System.Threading.Tasks; using System.Collections.Generic; using System.Text.Json.Serialization; public class TokenApiResponse { public bool IsSuccessful { get; set; } = false; public string Scope { get; set; } [JsonPropertyName("token_type")] public string TokenType { get; set; } [JsonPropertyName("expires_in")] public int ExpiresIn { get; set; } [JsonPropertyName("access_token")] public string AccessToken { get; set; } } class Program { static async Task Main(string[] args) { // Replace with your actual values var clientId = "YOUR_CLIENT_ID"; var clientSecret = "YOUR_CLIENT_SECRET"; var tokenUrl = "{{tokenUrl}}"; using var client = new HttpClient(); // Encode credentials (clientId:clientSecret) in Base64 var credentials = $"{clientId}:{clientSecret}"; var base64Credentials = Convert.ToBase64String( Encoding.UTF8.GetBytes(credentials) ); // Set headers client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", base64Credentials); try { var data = new[] { new KeyValuePair<string, string>("grant_type", "client_credentials"), }; var response = await client.PostAsync( tokenUrl, new FormUrlEncodedContent(data) ); if (!response.IsSuccessStatusCode) { throw new Exception($"HTTP error: {response.StatusCode}"); } var responseContent = await response.Content.ReadAsStringAsync(); // Deserialize JSON into DTO var tokenResponse = JsonSerializer.Deserialize<TokenApiResponse>( responseContent, new JsonSerializerOptions { PropertyNameCaseInsensitive = true } ); if (tokenResponse == null) { throw new Exception("Failed to deserialize token response."); } tokenResponse.IsSuccessful = true; Console.WriteLine($"Access token: {tokenResponse.AccessToken}"); } catch (Exception ex) { Console.WriteLine($"Error fetching token: {ex.Message}"); } } } JavaScript // If using Node <18, install node-fetch: // npm install node-fetch // const fetch = require("node-fetch"); const clientId = "YOUR_CLIENT_ID"; const clientSecret = "YOUR_CLIENT_SECRET"; const tokenUrl = "{{tokenUrl}}"; // DTO-style structure class TokenApiResponse { constructor(data) { this.isSuccessful = false; this.scope = data.scope; this.token_type = data.token_type; this.expires_in = data.expires_in; this.access_token = data.access_token; } } async function fetchToken() { try { // Encode credentials (clientId:clientSecret) in Base64 const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64"); const response = await fetch(tokenUrl, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", "Authorization": `Basic ${credentials}`, }, body: new URLSearchParams({ grant_type: "client_credentials", }), }); if (!response.ok) { throw new Error(`HTTP error: ${response.status}`); } const json = await response.json(); // Map response to DTO const tokenResponse = new TokenApiResponse(json); tokenResponse.isSuccessful = true; console.log("Access token:", tokenResponse.access_token); return tokenResponse; } catch (error) { console.error("Error fetching token:", error.message); return null; } } // Execute
• [Generate Signature](https://docs.miden.co/authentication/generate-signature.md): Authentication is required for all requests to the Miden API. It ensures that only authorized users or applications can access Miden services and interact with sensitive financial data. The authentication process involves two key components: Token Generation and Request Signature Generation. Overview To begin interacting with the Miden API, you must first obtain an access token. This is done by sending a request to the Get Token endpoint with valid credentials. If the request is successful, Miden will return an access token that grants temporary access to protected API endpoints. The access token must be included in the Authorization header of all subsequent API requests. Usage: Signature is essential for all API requests and must be included in the header of each request to ensure successful communication with the API. By generating a unique signature for each call, you authenticate your request, verify its integrity, and protect sensitive data from unauthorized access. This practice is crucial for maintaining the security and reliability of your interactions with the API, ensuring that only legitimate requests are processed. How to generate Your signature: When you interact with our API, generating a signature is crucial for authentication. This guide will help you understand how to create a signature using code samples in different programming languages. Step-by-step process: 1 Understand the signature structure: The signature is generated by combining several components: a. HTTP Method (GET, POST, etc.) b. Full URL of the request c. A unique reference string d. Your client ID e. Your client secret These components are concatenated in a specific order, hashed, and then encoded to produce the final signature. 2 Generate the unique reference: The reference is a unique string that helps ensure that each request is distinct. This can be generated using a nonce function that produces random strings. 3 Create the base string: The base string to be signed is constructed using this format: JavaScript HTTP_METHOD&ENCODED_URL&REFERENCE&CLIENT_ID&CLIENT_SECRET 4 Hashing and encoding The base string is hashed using SHA-1, and the resulting hash is then encoded in Base64. 5 Code samples Here are code snippets in PHP, Go, C#, and JavaScript (Node.js) to help you generate the signature. PHP //Generate AuthToken $credentials = $clientId . ':' . $clientSecret; $authorizationHeader = 'Basic ' . base64_encode($credentials); $apiResponse = Http::withHeaders([ 'Content-Type' => 'application/x-www-form-urlencoded', 'Authorization' => $authorizationHeader, ])->asForm()->post($tokenUrl, [ 'grant_type' => 'client_credentials', 'scope' => 'CardAPIs', ]); //Calculate signature $url = "full url of the request"; $encodeUrl = urlencode($url); $reference = nonce(); $clientId = "client Id generated during application creation"; $clientSecret = "generated during application creation"; $method = "Http method of the request"; $baseStringToBeSigned = $method . "&" . $encodeUrl . "&" . $reference. "&". $clientId . "&" . $clientSecret; $signature = Base64Encode(SHA1Here($baseStringToBeSigned)); function nonce() { return substr(str_shuffle(MD5(microtime())), 0, 20); } function Base64Encode($value): string { return base64_encode($value); } function Base64Decode($value): bool|string { return base64_decode($value); } function SHA256($signaturecipher): bool|string { return hash("sha256",$signaturecipher); } function SHA1Here($signatureCipher): string { return sha1($signatureCipher, false); } Go package main import ( "bytes" "encoding/base64" "fmt" "net/http" "net/url" ) func main() { url := "token_url" clientID := "your_client_id" clientSecret := "your_client_secret" credentials := clientID + ":" + clientSecret authHeader := "Basic " + base64.StdEncoding.EncodeToString([]byte(credentials)) client := &http.Client{} reqBody := url.Values{ "scope": []string{"CardAPIs"}, "grant_type": []string{"client_credentials"}, } req, err := http.NewRequest("POST", url, bytes.NewBufferString(reqBody.Encode())) if err != nil { fmt.Println("Error creating request:", err) return } req.Header.Set("Content-Type", "application/x-www-form-urlencoded") req.Header.Set("Authorization", authHeader) response, err := client.Do(req) if err != nil { fmt.Println("Error sending request:", err) return } defer response.Body.Close() fmt.Println("Response status:", response.Status) buf := new(bytes.Buffer) buf.ReadFrom(response.Body) fmt.Println("Response body:", buf.String()) } //Calculate signature package main import ( "fmt" "math/rand" "time", "crypto/sha1" "encoding/hex" ) func main() { url := "full url of the request" encodeUrl := url // Assuming URL encoding is not necessary in Go reference := nonce() clientId := "client Id generated during application creation" clientSecret := "generated during application creation" method := "Http method of the request" baseStringToBeSigned := fmt.Sprintf("%s&%s&%s&%s&%s", method, encodeUrl, reference, clientId, clientSecret) signature := sha1Here(baseStringToBeSigned) fmt.Println("Signature:", signature) } func nonce() string { rand.Seed(time.Now().UnixNano()) const letters = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789" b := make([]byte, 20) for i := range b { b[i] = letters[rand.Intn(len(letters))] } return string(b) } func sha1Here(data string) string { hasher := sha1.New() hasher.Write([]byte(text)) bytes := hasher.Sum(nil) return hex.EncodeToString(bytes) } C# using System; using System.Net; using System.Net.Http; using System.Net.Http.Headers; var client = new HttpClient(); var credentials = clientId + ":" + clientSecret; client.DefaultRequestHeaders.Add("Authorization", $"Basic {Base64Encode(credentials)}"); var data = new[] { new KeyValuePair<string, string>("scope", "CardAPIs"), new KeyValuePair<string, string>("grant_type", "client_credentials"), }; var apiResponse = await client.PostAsync(url, new FormUrlEncodedContent(data)); public static string Base64Encode(string plainText) { var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText); return System.Convert.ToBase64String(plainTextBytes); } //Calculate Signature using System; using System.Security.Cryptography; using System.Text; class Program { static void Main(string[] args) { string url = "full url of the request"; string encodeUrl = WebUtility.UrlEncode(url); string reference = Nonce(); string clientId = "client Id generated during application creation"; string clientSecret = "generated during application creation"; string method = "Http method of the request"; string baseStringToBeSigned = $"{method}&{encodeUrl}&{reference}&{clientId}&{clientSecret}"; string signature = Base64Encode(SHA1Here(baseStringToBeSigned)); Console.WriteLine($"Signature: {signature}"); } static string Nonce() { return Guid.NewGuid().ToString().Replace("-", "").Substring(0, 20); } static string SHA1Here(string data) { var sh = SHA1.Create(); var hash = new StringBuilder(); byte[] bytes = Encoding.UTF8.GetBytes(text); byte[] b = sh.ComputeHash(bytes); foreach (byte a in b) { var h = a.ToString("x2"); hash.Append(h); } return hash.ToString(); } } JavaScript //Signature Calculation exports.generateSignature = async (url, method) => { const crypto = require('crypto'); const { v4: uuidv4 } = require('uuid'); const encodeUrl = encodeURIComponent(url); const reference = nonce(); const clientId = `${process.env.MIDEN_CLIENT_ID}` const clientSecret = `${process.env.MIDEN_SECRET_KEY_TEST}` const baseStringToBeSigned = `${method}&${encodeUrl}&${reference}&${clientId}&${clientSecret}`; const hashValue = textToHash(baseStringToBeSigned); const signature = toBase64(hashValue); function nonce() { return uuidv4().replace(/-/g, '').substring(0, 20); } function sha1(data) { return crypto.createHash('sha1').update(data).digest('base64'); } function textToHash(text) { const hash = crypto.createHash('sha1'); // Create SHA-1 hash object hash.update(text, 'utf8'); // Update the hash with the text encoded in UTF-8 const hashHex = hash.digest('hex'); // Get the resulting hash as a hexadecimal string return hashHex; } function toBase64(input) { return Buffer.from(input).toString('base64'); } return signature } Python import base64 import hashlib import requests import urllib.parse import uuid # ========== CONFIGURATION ========== client_id = "your_client_id" client_secret = "your_client_secret" token_url = "https://your-auth-url.com/token" scope = "CardAPIs" request_method = "POST" target_url = "https://your-api-url.com/endpoint" # Full URL of the actual API request # ========== GET AUTH TOKEN ========== def get_access_token(): credentials = f"{client_id}:{client_secret}" encoded_credentials = base64.b64encode(credentials.encode()).decode() headers = { "Authorization": f"Basic {encoded_credentials}", "Content-Type": "application/x-www-form-urlencoded" } data = { "grant_type": "client_credentials", "scope": scope } response = requests.post(token_url, headers=headers, data=data) response.raise_for_status() return response.json()["access_token"] # ========== GENERATE NONCE ========== def generate_nonce(): return uuid.uuid4().hex[:20] # ========== SIGNATURE UTILITIES ========== def sha1_hash(text: str) -> str: return hashlib.sha1(text.encode('utf-8')).hexdigest() def base64_encode(text: str) -> str: return base64.b64encode(text.encode('utf-8')).decode() # ========== GENERATE SIGNATURE ========== def generate_signature(method: str, url: str, ref: str, client_id: str, client_secret: str) -> str: encoded_url = urllib.parse.quote(url, safe='') # equivalent of WebUtility.UrlEncode or urlencode base_string = f"{method}&{encoded_url}&{ref}&{client_id}&{client_secret}" sha1_result = sha1_hash(base_string) return base64_encode(sha1_result) # ========== MAIN ========== if __name__ == "__main__": # Get Access Token token = get_access_token() print("Access Token:", token) # Generate Signature reference = generate_nonce() signature = generate_signature(request_method, target_url, reference, client_id, client_secret) print("Reference:", reference) print("Signature:", signature) Signature Calculation: JavaScript //Signature Calculation exports.generateSignature = async (url, method) => { const crypto = require('crypto'); const { v4: uuidv4 } = require('uuid'); const encodeUrl = encodeURIComponent(url); const reference = nonce(); const clientId = ${process.env.MIDEN_CLIENT_ID} const clientSecret = ${process.env.MIDEN_SECRET_KEY_TEST} const baseStringToBeSigned = ${method}&${encodeUrl}&${reference}&${clientId}&${clientSecret}; const hashValue = textToHash(baseStringToBeSigned); const signature = toBase64(hashValue); function nonce() { return uuidv4().replace(/-/g, '').substring(0, 20); } function textToHash(text) { const hash = crypto.createHash('sha1'); // Create SHA-1 hash object hash.update(text, 'utf8'); // Update the hash with the text encoded in UTF-8 const hashHex = hash.digest('hex'); // Get the resulting hash as a hexadecimal string return hashHex; } function toBase64(input) { return Buffer.from(input).toString('base64'); } return signature } 'ref' is the reference passed in the header as part of the request. Hence: url encode the full url proceed to concatenate the verb, url, reference, clientId and secret. Finally, get a SHA1 of the concatenated string and then encode it as base64 string. Ensure that full values are being passed in the URL. Some code snippets might contain placeholder values for sensitive information like API keys. Remember to replace these placeholders with your actual credentials before using the code. All Request Methods passed must be in Uppercase.
• [Supported Authorization Decision Codes](https://docs.miden.co/authentication/supported-authorization-decision-codes.md): Overview Miden APIs return: Application response codes ( responseCode ) for business outcomes HTTP status codes for request-level outcomes Both must be evaluated together to determine the result of a request. Application Response Codes Success Code Description Finality 000 Success TerminalSuccess Validation / Request Errors (1xx) Code Description Finality 111 Invalid request amount TerminalFailure 112 Invalid card id TerminalFailure 113 Invalid unique key TerminalFailure 114 Max top-up limit exceeded TerminalFailure 115 Organization disabled / KYC not approved TerminalFailure 116 Insufficient funds TerminalFailure 117 Card not active TerminalFailure 119 Transaction not permitted TerminalFailure 121 Currency not supported TerminalFailure 122 Invalid card PIN TerminalFailure 123 Invalid cardholder name TerminalFailure 124 Invalid card expiry date TerminalFailure 125 MID not allowed TerminalFailure 126 Country not supported TerminalFailure 127 MCC not supported TerminalFailure 128 Suspicious transaction TerminalFailure 129 Transaction limit exceeded TerminalFailure 130 Velocity limit exceeded TerminalFailure 131 Invalid request TerminalFailure 132 Invalid date request TerminalFailure 133 Invalid transaction TerminalFailure 134 Invalid merchant TerminalFailure 135 Invalid account TerminalFailure 136 Format error TerminalFailure 137 Security error TerminalFailure 138 Duplicate transaction TerminalFailure 139 Duplicate request TerminalFailure 140 Do not honour TerminalFailure 141 Restricted card TerminalFailure 142 Card expired TerminalFailure 143 Card closed TerminalFailure 144 Card lost or stolen TerminalFailure 145 Fraudulent transaction TerminalFailure 146 Authentication failed TerminalFailure 147 PIN tries exceeded TerminalFailure 148 No card record TerminalFailure 149 Unauthorized TerminalFailure System / Processing Errors (15x, 17x) Code Description Finality 150 System malfunction Indeterminate 151 System timeout Indeterminate 152 Terminal processor error Indeterminate 153 Cash service not available Indeterminate 154 Law violation TerminalFailure 155 AML requirement not fulfilled TerminalFailure 156 File temporarily unavailable Indeterminate 157 Unable to locate record TerminalFailure 158 Requested information missing TerminalFailure 159 Duplicate transmission TerminalFailure 160 Stop payment order TerminalFailure 161 Negative balance exceeds limit TerminalFailure 162 Invalid track data TerminalFailure 163 Invalid EMV data TerminalFailure 164 Invalid partial auth amount TerminalFailure 165 Amount exceeds preauth TerminalFailure 166 Re-enter transaction Indeterminate 167 Refer to issuer Indeterminate 168 Refer to issuer (special condition) Indeterminate 169 No issuer Indeterminate 170 No action taken Indeterminate 171 No financial impact Indeterminate 172 Issuer/switch timeout Indeterminate 173 Institution not found TerminalFailure 174 Unsolicited reversal Indeterminate 175 Already reversed TerminalFailure 176 Authorization declined TerminalFailure 177 Authorization error Indeterminate 178 Request error TerminalFailure 179 No reason to decline Indeterminate 180 Verification failed TerminalFailure 181 OFAC failed TerminalFailure 182 KYC failed TerminalFailure 183 KYC manual review required Indeterminate 184 Address verification failed TerminalFailure 185 ID verification failed TerminalFailure 186 Merchant blacklisted TerminalFailure 187 Card account verification error Indeterminate 188 No valid CVV verification TerminalFailure 189 Frequency limits exceeded TerminalFailure 911 System exception Indeterminate PIN / Card / Account States (2xx) Code Description Finality 201 Incorrect PIN TerminalFailure 202 Invalid PIN TerminalFailure 203 No PIN assigned TerminalFailure 204 PIN already present TerminalFailure 205 No PIN card TerminalFailure 206 PIN confirmation failed TerminalFailure 207 Card not effective TerminalFailure 208 Restricted card (pickup) TerminalFailure 209 Special conditions (pickup) TerminalFailure 210 Stolen card (pickup) TerminalFailure 211 Fraudulent use (pickup) TerminalFailure 212 Lost card (pickup) TerminalFailure 213 Call acquirer security Indeterminate 214 Call acquirer security (pickup) Indeterminate 215 Card closed (pickup) TerminalFailure 216 Suspected fraud TerminalFailure 217 Invalid amount / insufficient funds TerminalFailure 218 Cardholder cancelled TerminalFailure 219 Issuer cancelled TerminalFailure 220 Cardholder deceased TerminalFailure 221 Account closed TerminalFailure 222 Account frozen TerminalFailure 223 Account not available TerminalFailure 224 Account not qualified TerminalFailure 225 Receiving institution not qualified TerminalFailure 226 Entry refused by receiver TerminalFailure 227 Returned on originator request TerminalFailure 228 Authorization revoked TerminalFailure 229 Credit previously issued TerminalFailure 230 Credit not processed Indeterminate 231 Warning bulletin Indeterminate 232 Authorization not obtained TerminalFailure 233 Transaction not reconciled Indeterminate 234 Account number not on file TerminalFailure 235 Transaction amount differs TerminalFailure 236 No cardholder authorization TerminalFailure 237 Fraudulent processing TerminalFailure 238 Cardholder denies TerminalFailure 239 Duplicate processing TerminalFailure Risk & Compliance (3xx) Code Description Finality 301 Fraud rule triggered TerminalFailure 302 Behavioural risk triggered TerminalFailure 303 Device risk triggered TerminalFailure 304 Geo risk triggered TerminalFailure 305 Sanctions screening failed TerminalFailure 306 PEP match found TerminalFailure 307 AML risk triggered TerminalFailure 308 High-risk merchant TerminalFailure 309 High-risk country TerminalFailure 310 Program restriction TerminalFailure HTTP Status Codes Code Description Finality 200 Success Terminal 400 Invalid request parameters Terminal 401 Authentication failed Terminal 403 Authorization failure Terminal 404 Resource not found Terminal 422 Business rule violation Terminal 429 Rate limit exceeded Indeterminate (retry) 500 Internal server error Indeterminate 502 Upstream provider error Indeterminate 503 Service unavailable Indeterminate 504 Processor timeout Indeterminate Finality Definitions Type Meaning TerminalSuccess Request completed successfully TerminalFailure Do not retry without fixing input/state Indeterminate Outcome unknown; retry or check status How to handle responses Use HTTP status codes to confirm request handling Use responseCode to determine business outcome Recommended behavior Success ( 000 ) → proceed TerminalFailure → fix request or state before retry Indeterminate → retry cautiously or check transaction status 000 is the only successful application response code Always evaluate both HTTP status and responseCode Retry only when the outcome is indeterminate Avoid retrying terminal failures without changes
• [Idempotency in Miden APIs](https://docs.miden.co/authentication/idempotency-in-miden-apis.md): Overview Idempotency is a critical feature of Miden's APIs, designed to ensure safe, reliable API interactions, even in the event of network disruptions or failures. When making requests to Miden's critical endpoints, users can rely on idempotency to avoid unintended side effects like duplicate transactions or repeated actions. What is Idempotency? Idempotency ensures that repeated requests with the same parameters produce the same result without causing duplication or undesired outcomes. For instance, if a request is made to create a Card Customer, and the network times out or an error occurs, re-sending the same request will not create multiple customers as long as it is correctly configured. How to Implement Idempotency To make a request idempotent, Miden requires you to include a Reference header with a unique value, which acts as an idempotency key. This Reference header uniquely identifies each request, allowing Miden to track and manage it across multiple retries. Here’s how it works: Reference Header : Include a unique value in the "Reference" header for every request that you want to make idempotent. Validity Period : Miden will store this reference for 24 hours . Any repeated requests during this period with the same reference will produce the same result, ensuring no duplication. Retrying Requests : If your original request fails or times out, you can retry it by sending the same Reference value. Miden will recognize that the request has already been processed (or is in process) and return the appropriate response without executing the operation again. Conditions for Idempotent Requests To make a request idempotent: Pass a unique "Reference" value in the request header. Do not change the payload —the data in the body of the request should be the same for retries. Retry within 24 hours —subsequent retries using the same reference key must occur within this period for Miden to guarantee idempotency. Responses and Error Handling If the original request succeeded , any subsequent request with the same Reference will return a 400 Bad Request error with the message: "The Reference value has already been seen in the last 24 hours." If the original request failed , retrying with the same Reference will ensure the operation is processed once, preventing duplication. Example Scenario Let’s say you’re creating a Card Customer, and your request times out. If you retry the request with the same Reference value in the header, Miden will check if the original request was processed: If the original request was successful , the retry will not create another Card Customer. If the original request failed or timed out , the retry will attempt the operation again without causing duplication. This ensures that even in the face of network issues, your request is handled only once, maintaining data integrity and preventing unintended consequences. Idempotency in Miden’s APIs is vital for robust and error-tolerant applications. Always ensure you use a unique Reference for each new operation to maximize the benefits of idempotency in your API interactions.
• [Card KYC](https://docs.miden.co/card-issuance/card-kyc.md): Overview Card KYC is the identity verification step required before a payment card can be issued. Every customer must successfully complete either Individual KYC or Business KYB verification before card issuance. Upon successful verification, Miden returns a Customer ID , which is required for card issuance and subsequent card management operations. Card Issuance Flow Based on the customer type and identification method provided, Miden automatically determines the appropriate verification flow. Individual customers may be verified using Passport, Driver's License, National ID, BVN, or NIN, depending on what is applicable for their country while business customers are verified through the Business KYC (KYB) flow. Document-based individual verification. BVN verification. NIN verification. Business verification, also known as KYB. Verification Paths Verification path Applicable To Required Identification Processing Government ID Verification Individual International Passport, Driver's Licence, National ID, Voter's Card, Ghana Card, or other supported government-issued identity document Asynchronous BVN verification Individual (Nigeria only) BVN Synchronous NIN verification Individual (Nigeria only) NIN Synchronous Business Verification (KYB) Business Registration documents Asynchronous Note Government ID verification supports both Nigerian and non-Nigerian customers using supported government-issued identification documents. Important A successful verification returns a customerId . This value must be supplied when issuing or reissuing cards and should be stored securely by your application.
  • [Individual KYC Verification](https://docs.miden.co/card-issuance/card-kyc/individual-kyc-verification.md): Identity Document Verification Use this verification method when verifying an individual using a supported government-issued identity document. The supported document depends on the customer's country and available verification methods. Document-based verification applies when an individual submits an identity document such as: International Passport Driver’s licence Voter’s card National ID Ghana Card Other government-issued identity documents (where supported) The customer’s identity document image must be supplied through individualKyc.idFrontImage . The document may be supplied as: A Base64-encoded string. A valid data URI. After a successful submission, Miden returns a kycToken and an initial KYC status of Initiated . The verification then progresses asynchronously through the following lifecycle: Flowchart BVN Verification BVN verification is available only to Nigerian individual customers. BVN verification is available only for customers whose country is Nigeria. No document image is required. The request must contain: First name. Last name. BVN as idNumber . Nigerian address information. The verification is approved where either the verified BVN holder’s first name or last name matches the name supplied in the request. BVN verification is synchronous. The response returns either Approved or Rejected . For successful BVN verification, the submitted BVN may be returned as the kycToken . NIN Verification NIN verification is available only to Nigerian individual customers. NIN verification is available only for customers whose country is Nigeria. No document image is required. The request must contain: First name. Last name. Date of birth. NIN as idNumber . Nigerian address information. The date of birth must be provided in YYYY-MM-DD format. NIN verification is synchronous. The response returns either Approved or Rejected . For successful NIN verification, the submitted NIN may be returned as the kycToken . Supported Individual ID Types The following document types are supported for document-based verification. ID types Document or Number Description PASSPORT Identity Document International Passport NIN Identity Number Nigerian National Identification Number BVN Identity Number Bank Verification Number NATIONAL_ID Identity Document National identity card vNIN Identity Number Virtual National Identification Number DRIVERS_LICENSE Identity Document Driver’s licence VOTERS_CARD Identity Document Voter’s card GHANA_CARD (for Ghanaian customers, if supported) Identity Document Ghana national identity card Important A successful individual KYC verification returns a Customer ID. This Customer ID is required for subsequent card issuance requests.
  • [Business KYB Verification](https://docs.miden.co/card-issuance/card-kyc/business-kyb-verification.md): KYB Business KYB verification validates the registration details of a business before a Customer ID can be created for card issuance. Once verification is approved, a Customer ID is returned and can be used to issue corporate cards. T The businessKyc object should include: Registered business name Business registration number Registered or operating business address Country State or Province City Postal/ZIP code (where applicable) Business verification is processed asynchronously. After submission, the API returns a kycToken . Use this token to retrieve the latest verification status or correlate Card KYC webhook events until verification is completed. After submission, use the returned kycToken to retrieve the latest verification status or listen for Card KYC webhook events. Flowchart Business KYB verification is asynchronous. After submission, the verification request enters the verification lifecycle and progresses through the following statuses until a final decision is reached. Important A successful Business KYB verification returns a Customer ID. This Customer ID is required for all subsequent business card issuance requests.
  • [Card KYC Status Lifecycle](https://docs.miden.co/card-issuance/card-kyc/card-kyc-status-lifecycle.md): Asynchronous Verification Lifecycle Document and business verification requests follow an asynchronous lifecycle. Synchronous Verification BVN and NIN verification are completed during the API request. Status Definitions Status Description Initiated Verification has started. Pending Verification is currently in progress. Approved Verification completed successfully. Rejected Verification was unsuccessful. Note Only asynchronous verification methods (Document Verification and Business KYB) progress through the Initiated and Pending statuses. Synchronous verification methods (BVN and NIN) return an Approved or Rejected result immediately.
  • [Client Reference & Request Idempotency](https://docs.miden.co/card-issuance/card-kyc/client-reference-and-request-idempotency.md): Overview The Card KYC APIs use two identifiers for different purposes: clientReference — A merchant-generated identifier used to correlate KYC requests with your internal customer records. Reference Header — An idempotency key that prevents duplicate processing of the same API request. clientReference clientReference is your internal reference for the customer or verification request. It is returned in: KYC submission responses. KYC status information. KYC webhook events. Use it to reconcile Miden KYC records with your internal customer records. The clientReference is returned in all KYC responses and webhook notifications, allowing you to easily reconcile verification results with your internal customer records. Reference Header The Reference header is the idempotency reference for the API request. Reusing the same Reference value for the same request prevents duplicate KYC submissions. It should: Be unique for each new KYC submission. Be retained when safely retrying the same request. Not be reused for a different customer or KYC submission. Recommended KYC Integration Flow Recommended Customer Handling Approved When KYC is approved: Mark the customer as verified. Continue with card issuance using the returned customerId Store the customerId , kycToken , and clientReference . Retain the verification result for audit and reconciliation. Pending When KYC is pending: Inform the customer that verification is still in progress. Do not repeatedly submit the same KYC request. Poll the KYC Status endpoint or wait for KYC webhook notifications. Rejected When KYC is rejected: Review rejectType and rejectLabels , where provided. Determine whether the customer may retry. Display the rejection reason returned by the API or webhook and allow the customer to resubmit where applicable. Avoid exposing internal provider details directly to the customer.
  • [Security Best Practices](https://docs.miden.co/card-issuance/card-kyc/security-best-practices.md): Overview Card KYC requests contain sensitive customer identity information. Merchants are responsible for protecting this data throughout its collection, transmission, processing, and storage. Your integration should: Use HTTPS for all requests. Protect authentication credentials. Avoid logging full BVNs, NINs, document numbers, or identity images. Encrypt KYC information at rest. Restrict access to verification records. Validate document file type and size before submission. Validate webhook signatures before processing events. Store only information required for compliance and reconciliation. Follow applicable privacy, data-protection, and card-program requirements. Best Practices Validate required fields before calling the API. Use the correct verification path for the selected customer type. Ensure BVN and NIN customers have a Nigerian address country. Supply dateOfBirth in YYYY-MM-DD format. Use unique Reference and clientReference values. Store the returned customerId and kycToken . Use webhooks as the primary source for asynchronous status updates. Poll the status endpoint only when necessary. Stop polling after a final status of Approved or Rejected . Process webhook events idempotently. Use eventId to detect duplicate webhook deliveries. Do not issue or activate restricted card services before KYC approval.
• [Miden-Managed Processes](https://docs.miden.co/card-issuance/miden-managed-processes.md): Authorization Models Miden supports two authorization models for card transactions. You can choose the model that best fits your business and technical requirements. 1. Miden-Managed Authorization In the default integration model, Miden manages the entire card authorization lifecycle on your behalf. When a card transaction is initiated, Miden performs all required authorization checks, evaluates the transaction against the configured card controls, and returns an authorization decision to the card network. No additional integration is required. This model is recommended for merchants who want a simple integration while Miden manages the underlying card processing complexity. What Miden Handles With Miden-Managed Authorization, Miden is responsible for: Card transaction authorization Available balance validation Card funding Spend limit enforcement Card status validation Transaction processing Settlement lifecycle management Card termination and regularization Webhook notifications for transaction events Merchants simply integrate with the available Cards APIs while Miden manages the authorization process behind the scenes. 2. Customer-Managed Authorization Customer-Managed Authorization enables you to make authorization decisions within your own systems. Instead of Miden automatically approving or declining card transactions, Miden forwards every authorization request to your authorization endpoint in real time. Your application evaluates the transaction and returns an approval or decline response. Miden continues to manage card network connectivity, transaction processing, settlement, and the overall card lifecycle, while your system controls the authorization decision. This model is recommended for organizations that maintain their own: Risk engine Fraud detection system Customer ledger Spend control engine Compliance rules Internal authorization policies How It Works When a cardholder attempts a transaction: The card network routes the authorization request to Miden. Miden sends the authorization request to your configured Authorization URL. Your application evaluates the transaction. Your application returns an approval or decline response. Miden forwards the decision to the card network. Miden continues processing the remainder of the transaction lifecycle. Your authorization endpoint must return a response within 400 milliseconds . If no response is received within this timeframe, Miden applies your configured Default Authorization Decision . Configuration Before your system can receive authorization requests, Customer-Managed Authorization must be enabled for your organization. Once enabled, navigate to: Settings → Developer → Card Transaction Authorization Configure the following fields. Field Description Authorization URL The publicly accessible HTTPS endpoint that will receive authorization requests from Miden. Default Authorization Decision The action Miden should take when your endpoint does not respond within 400 milliseconds. Supported default decisions are: Auto Approve Auto Decline Integration Flow Request Types The requestType field identifies the type of card transaction event being processed. Supported values include: Request Type Description Authorization New purchase authorization request PreAuthorization Pre-authorization (fund reservation) request Settlement Transaction settlement event PartialReversal Partial reversal of a previous transaction Reversal Full reversal of a previous transaction Refund Refund transaction CashWithdrawal ATM or cash withdrawal transaction
  • [Card Issuance](https://docs.miden.co/card-issuance/miden-managed-processes/card-issuance.md): Overview Use the Card Issuance endpoints to create and reissue retail, corporate, and lite cards. Endpoints Issue Retail Card Issue Corporate Card Issue Lite Card Re-issue Card Contactless Payment For retail, corporate, and re-issue requests, the contactlessPayment field is set to true only when issuing a card that should be enabled for contactless payment and digital wallet. Spending Limits & Transaction Acceptance The following fields are optional and apply only to spending limits and transaction acceptance: cardLimits cardLimits.dailyLimit cardLimits.transactionLimit whiteListedMccs blackListedMccs Card re-issuance rules If sharedBalance is true , do not pass initialBalance . If sharedBalance is false , do not pass cardId . address is optional. If omitted, the address used for the original card is reused. Lite Card Behaviour Lite cards are not reloadable They terminate when: the configured swipeCount is reached, or the card balance is exhausted
  • [Lite Cards](https://docs.miden.co/card-issuance/miden-managed-processes/lite-cards.md): Description: This endpoint allows you to issue a Lite Card for a customer with a predefined balance and a fixed number of allowed swipes. Lite Cards are designed for controlled, limited-use scenarios . They cannot be topped up after issuance and are intended to terminate automatically once either of the following happens: the configured swipe count is exhausted, or the card runs out of balance This makes Lite Cards suitable for one-off or tightly restricted spending use cases where card usage must end automatically based on spend or usage count. Usage Options: Use this endpoint when you need to issue a card that should operate within strict limits and terminate automatically without further funding. Lite Cards are best suited for use cases such as: vouchers or benefit disbursements one-time or short-term spending programs controlled customer incentives fixed-purpose cards with limited transaction count For example, if a Lite Card is issued with: a card balance of $20 , and a swipe count of 3 the cardholder can use the card up to 3 times, and the card will terminate on the third successful swipe or earlier if the balance is depleted before then. Because Lite Cards cannot be topped up , they are ideal where spend control and automatic card closure are required.
  • [Card Info](https://docs.miden.co/card-issuance/miden-managed-processes/card-info.md): Overview The Card Info module provides APIs for retrieving card and customer data within the Miden system. These endpoints allow you to: Access card details (masked or full PAN) Retrieve customer records List and filter cards across your system Use these APIs for display, reporting, monitoring, and administrative operations . Endpoints 1. Get Card Details (Masked PAN) (Link to endpoint) Description Retrieves card details with the Primary Account Number (PAN) masked , exposing only partial digits (first 6 and last 4). Usage Use this endpoint when: Displaying card details in user interfaces Handling customer support queries Generating reports without exposing sensitive data This is the recommended default for most use cases. 2. Get Card Details (Full PAN) (Link to endpoint) Description Retrieves full card details, including the complete PAN and CVV , along with additional card metadata and billing details. Usage Use this endpoint only when: Full card details are required for secure workflows Performing backend operations or provisioning Handling sensitive administrative processes This endpoint returns sensitive data and should be used in secure, PCI-compliant environments only. 3. All Customers (Link to endpoint) Description Retrieves a list of all customers (cardholders) in the system. Usage Use this endpoint for: Customer management and administration Reporting and audits Fetching customer records for further processing 4. All Cards (Link to endpoint) Description Retrieves all cards within the system, including their status, type, and associated metadata. Usage Use this endpoint for: Monitoring card issuance and activity Managing card inventory Supporting customer inquiries Administrative reporting Summary The Card Info module enables flexible and secure access to card and customer data: Use Masked PAN for safe, general-purpose access Use Full PAN only for authorized, sensitive operations Use All Customers and All Cards for listing, filtering, and reporting With support for filtering and pagination, these endpoints allow you to efficiently retrieve exactly the data you need.
  • [Card Transactions](https://docs.miden.co/card-issuance/miden-managed-processes/card-transactions.md): Overview The Card Transactions module provides APIs for tracking and managing card-related financial operations. These endpoints enable you to: Retrieve transaction history Move funds between wallets and cards Retry failed transactions Perform operational actions such as transfers and withdrawals They are primarily used for reporting, reconciliation, and balance management. Endpoints Get All Card Transactions Retrieves a paginated list of transactions across cards. Supports filtering by: date range card ID transaction type currency Use this endpoint for: auditing card activity generating reports investigating transaction history 2. Card Top-Up Credits funds from your wallet to a card. Use this endpoint when: funding a card for spending increasing available card balance Behavior Debits the specified amount from your wallet Credits the same amount to the card 3. Card Withdrawal Moves funds from a card back to your wallet. Use this endpoint when: removing funds from a card, eg, decline fees closing or decommissioning a card correcting funding actions Behavior Debits the specified amount from the card Credits your wallet Card must maintain a minimum balance of $1 4. Reprocess Pending Cross-Border Charges Retries previously failed cross-border transactions. Use this endpoint when: a transaction failed due to insufficient funds the card has since been funded you want to reattempt settlement Behavior Attempts to process pending international charges again Applies current card balance at time of retry 5. Card-to-Card Transfer Transfers funds between two cards within the same system. Use this endpoint when: reallocating funds between cards managing team or departmental budgets redistributing balances across users Behavior Debits the source card Credits the beneficiary card Summary Top-Up: Wallet → Card Withdrawal: Card → Wallet Transfer: Card → Card Reprocess: Retry failed cross-border charges Transactions: Retrieve transaction history
  • [Card Transaction Stages](https://docs.miden.co/card-issuance/miden-managed-processes/card-transaction-stages.md): Overview The Card Transactions module covers the lifecycle of a card transaction, from initiation to completion, including post-transaction adjustments. Transactions do not follow a strictly linear flow—depending on timing and outcome, they may be settled, reversed, or refunded . Transaction Flow Transaction Stages 1. Authorization Authorization is the initial step in a card transaction. When a cardholder initiates a payment, a request is sent to the issuer to: Validate the card Check available balance or limits Apply rules (e.g., MCC restrictions, card status) If approved: The transaction is authorized The amount is reserved (held) Funds are not yet transferred 2. Reversal (Void) A reversal cancels a transaction before it is settled. When a reversal occurs: The authorization is cancelled The held funds are released back to the cardholder No funds are transferred Used for: Cancelled purchases Failed or interrupted transactions 3. Settlement Settlement finalizes a transaction. During this stage: The reserved funds are captured and transferred to the merchant The transaction becomes completed 4. Refund (Return) A refund occurs after settlement. When a refund is processed: Funds are returned to the cardholder The original transaction remains recorded Used for: Returned goods Service cancellations Billing adjustments Summary Authorization → Validates and reserves funds Reversal → Cancels before settlement (releases hold) Settlement → Transfers funds to merchant Refund → Returns funds after settlement
  • [Regularize Terminated Card Balance](https://docs.miden.co/card-issuance/miden-managed-processes/regularize-terminated-card-balance.md): Description This endpoint is used to regularize a terminated card that has a negative balance at the time of termination. When a card is terminated with an outstanding negative balance, the system clears that debt by debiting your position (wallet) with us, bringing the card balance back to 0.00 . This allows you to settle the card liability internally with their own cardholder afterward. This endpoint should only be used for terminated cards with a negative balance . Notes If a card is Active and has a negative balance, this endpoint is not needed. The cardholder simply needs to fund the card with the outstanding negative amount to bring the balance back to zero. If a card is Terminated and still has a negative balance, the balance must be regularized through this endpoint. A customer cannot continue issuing or creating new cards while there is an outstanding negative balance on an existing card, whether Active or Terminated . The negative balance must first be settled. Business Logic Summary Active card + negative balance: the cardholder should top up the card by the negative amount. Terminated card + negative balance: use this endpoint to debit the customer’s position and reset the card balance to zero. Outstanding negative balances: must be resolved before the customer can create or issue additional cards.
  • [Merchant Controls (Whitelist & Blacklist Merchants)](https://docs.miden.co/card-issuance/miden-managed-processes/merchant-controls-whitelist-and-blacklist-merchants.md): Overview Merchant Controls define where a card can be used by applying rules based on Merchant IDs (MIDs) at authorization time. They enable: restricting specific merchants allowing only approved merchants handling exceptions without changing permanent rules All controls are applied per card and enforced in real time during transactions. Control Models Blacklist (Block List) Prevents transactions with specified merchants. Blocked MIDs → declined All others → allowed Used for risk, fraud, or compliance controls. Whitelist (Allow List) Restricts transactions to only specified merchants. Allowed MIDs → approved All others → declined Used for strict, controlled spending environments. Operations Balcklist Merchant Adds merchants to the blacklist → transactions with those MIDs are declined. Remove Merchant Blacklist Removes merchants from the blacklist → transactions are allowed again. Whitelist Merchant Restricts card usage to only specified merchants. Remove Merchant Whitelist Removes merchants from the whitelist → card returns to default or other applied rules. One-Time Unblock Temporarily bypasses a blacklist rule for a single transaction attempt . Applies once Automatically reverts afterward Rule Behavior Blacklist only → blocks specific merchants Whitelist only → allows only specified merchants Both present → whitelist typically dominates (stricter control) Temporary vs Persistent Controls Title Description Type Behavior Persistent Block, Unblock, Whitelist, Remove Whitelist Temporary One-Time Unblock (auto-reverts after one attempt) Multi-Merchant Support All operations can handle: a single MID multiple MIDs in one action Each MID is processed independently within the card’s configuration. Transaction Flow Practical Patterns Fraud Control Use blacklist to block risky merchants Vendor Locking Use whitelist to restrict card usage to specific vendors Exception Handling Use one-time unblock to allow a single transaction without changing rules Policy Updates Adjust controls dynamically using add/remove operations Key Principles Controls are evaluated per transaction Whitelist = restrictive , Blacklist = selective blocking Overrides are temporary and safe Rules can be combined and updated dynamically
  • [NGN Card Activation Flow](https://docs.miden.co/card-issuance/miden-managed-processes/ngn-card-activation-flow.md): Overview NGN Card activation defines the steps required to move a card from created to ready for transactions . Issuing a card alone does not guarantee usability—additional configuration may be required depending on card type and use case. Flow Step 1 Card Issued Step 2 PIN Set (NGN only) Step 3 Controls Applied (optional) Step 4 Ready for Use Steps 1. Card Issued The card is created and assigned to a customer. At this point, it exists but may not yet support all transaction types. 2. PIN Set (NGN Only) For NGN cards, a PIN must be set to enable PIN-authenticated transactions such as ATM withdrawals and POS payments. This step is required for full functionality. 3. Controls Applied (Optional) Additional configurations can be applied based on requirements: restrict or allow specific merchants define spending limits enforce usage policies This step shapes how the card behaves in production. 4. Ready for Use The card can now process transactions. During each transaction: merchant rules are evaluated limits are enforced PIN is validated (if applicable) Notes NGN cards require a PIN before use in most cases Controls can be added or modified at any time Card behavior is determined dynamically at authorization Examples Basic Flow Issue → Set PIN → Use Restricted Usage Issue → Set PIN → Apply controls → Use within limits Key Idea A card becomes fully usable only after completing the necessary configuration steps , not at issuance alone.
• [Customer-Managed Processes](https://docs.miden.co/card-issuance/customer-managed-processes.md): Overview By default, Miden manages card transaction authorization decisions on behalf of merchants. Under this model, Miden evaluates card transactions, applies the relevant card controls, and determines whether each transaction should be approved or declined. This section (Customer-Managed Card Transaction Authorization) is designed for merchants that prefer to make these authorization decisions within their own systems. When Customer-Managed Card Transaction Authorization is enabled, Miden sends card transaction events to the merchant’s configured authorization endpoint in real time. The merchant evaluates each request using its own balance records, transaction rules, fraud controls, customer limits, and other internal decision criteria, then returns an approval or decline response. Miden applies the merchant’s decision and returns the transaction result to the card network or switch. Miden continues to manage card-network connectivity and transaction processing. The merchant is responsible for making the authorization decision within the agreed response time. Usage When to Use Customer-Managed Authorization Use Customer-Managed Card Transaction Authorization when your organization needs to: Maintain card balances within its own ledger or core system. Apply proprietary authorization rules. Approve or decline transactions using internal customer balances. Apply custom fraud, risk, compliance, or spending controls. Make authorization decisions based on customer-specific business logic. Control transaction funding decisions in real time. Maintain direct control over card transaction approvals and declines. Customer-Managed Authorization is suitable for merchants with systems that can evaluate and respond to authorization requests in real time. Flowchart Prerequisites Before enabling Customer-Managed Card Transaction Authorization, ensure that your system has: A publicly accessible HTTPS endpoint. A reliable authorization service. Low-latency request processing. Internal card or customer balance records. Authorization decision rules. Fraud and risk controls. Monitoring and alerting. Request and response logging. A configured default authorization decision. A webhook endpoint for transaction and card lifecycle notifications. Processes for settlement, reversal, and refund reconciliation.
  • [Miden-Managed vs Customer-Managed Cards](https://docs.miden.co/card-issuance/customer-managed-processes/miden-managed-vs-customer-managed-cards.md): Area Miden-Managed Cards Customer-Managed Cards Card authorization decision Miden Merchant Card balance management Miden Merchant Transaction funding decision Miden Merchant Card-network connectivity Miden Miden Transaction routing Miden Miden Authorization rules Miden-managed controls Merchant-defined rules Default authorization decision Managed by Miden Configured by the merchant Authorization endpoint Not required Required Authorization response time Managed internally by Miden Merchant must respond within the agreed response time Webhook delivery Miden sends webhooks Miden sends webhooks Freeze, unfreeze, and termination requests Merchant calls Miden APIs Merchant calls Miden APIs Card limits Managed through Miden APIs Managed through Miden APIs
  • [Responsibilities](https://docs.miden.co/card-issuance/customer-managed-processes/responsibilities.md): Miden Responsibilities Miden is responsible for: Receiving card transaction requests from the card network or switch. Sending eligible transaction events to the merchant’s authorization endpoint. Applying the approval or decline decision returned by the merchant. Applying the configured default authorization decision where no valid response is received within the agreed response time. Returning the transaction decision to the card network or switch. Maintaining card-network connectivity. Processing card transaction events. Providing card-management APIs. Sending transaction and card lifecycle webhooks. Merchant Responsibilities The merchant is responsible for: Providing a publicly accessible authorization endpoint. Maintaining the availability and performance of the authorization endpoint. Authenticating and validating requests received from Miden. Evaluating the customer’s available balance. Evaluating transaction limits and internal controls. Applying fraud, risk, and compliance rules. Returning a valid approval or decline response within the agreed response time. Maintaining accurate internal customer and card balances. Processing Miden webhook events. Reconciling authorization, settlement, reversal, and refund events. Monitoring authorization failures and response latency.
  • [Configuration](https://docs.miden.co/card-issuance/customer-managed-processes/configuration.md): Before receiving authorization requests, configure your authorization settings in the Miden Portal. Step 1: Navigate to Developer Settings Log in to the Miden Portal. Navigate to Settings . Select Developer . Open the Card Transaction Authorizations tab. Step 2: Configure Authorization Settings Provide the following details: Field Description Authorization URL Publicly accessible HTTPS endpoint that receives card transaction requests from Miden. Default Authorization Decision Decision Miden applies when a valid response is not received within the agreed response time. Available Default Decisions Auto Approve Auto Decline Once the configuration is saved, Miden can begin sending supported card transaction events to the configured authorization endpoint.
  • [Authorization Flow](https://docs.miden.co/card-issuance/customer-managed-processes/authorization-flow.md): When a supported card transaction event occurs, Miden sends an HTTP POST request to the merchant’s configured Authorization URL. The merchant must evaluate the transaction and return a valid response within the agreed response time. The current integration guide specifies a response period of 400 milliseconds . Where a valid response is received within this period: A responseCode of 000 approves the transaction. A supported non- 000 responseCode declines the transaction. Where no valid response is received within the agreed response time, Miden applies the merchant’s configured Default Authorization Decision. End-to-End Authorization Flow Note The merchant’s Authorization URL must: Be publicly accessible. Use HTTPS. Accept HTTP POST requests. Accept JSON request bodies. Return HTTP 200 OK for valid authorization decisions. Respond within the agreed response time. Remain available during card transaction processing. Support the expected transaction volume. Handle duplicate or repeated events safely. Log incoming requests and outgoing decisions.
  • [Supported Request Types](https://docs.miden.co/card-issuance/customer-managed-processes/supported-request-types.md): Overview When Customer-Managed Authorization is enabled, Miden may send different types of card transaction requests to the merchant's configured authorization endpoint. The requestType field identifies the type of transaction being processed and allows the merchant to apply the appropriate business logic before returning a decision. Request Types The requestType field identifies the type of card transaction event sent to the merchant. Request Type Description Authorization Standard card authorization request requiring an approval or decline decision. PreAuthorization Authorization request used to reserve an amount before final transaction completion. Settlement Transaction request associated with completion or settlement of a previously authorized transaction. PartialReversal Reverses part of a previously authorized amount. Reversal Reverses a previously authorized transaction or amount. Refund Returns funds for a previously completed transaction. CashWithdrawal Represents a cash withdrawal transaction. The merchant may apply different processing and decision rules based on the requestType . Request-Type Processing Guidance Authorization Use the Authorization request type for a new purchase attempt. The merchant should: Confirm that the customer or card is active. Confirm that sufficient funds are available. Check transaction and daily limits. Apply fraud and compliance controls. Return an approval or decline decision. PreAuthorization Use the PreAuthorization request type when funds are being reserved before final settlement. The merchant should: Confirm that sufficient funds are available. Reserve the applicable amount internally. Prevent reserved funds from being reused. Maintain the transaction reference for later settlement or reversal. Settlement A Settlement event indicates that an authorized transaction has moved to settlement. The merchant should: Match the settlement to the preceding authorization. Apply the final settlement amount. Reconcile differences between the authorization and settlement amounts. Release or adjust any previously reserved amount. PartialReversal A PartialReversal reverses only part of a previous transaction. The merchant should: Identify the original transaction. Validate the partial reversal amount. Release or return only the reversed portion. Maintain the remaining transaction amount. Reversal A Reversal cancels a previous authorization or transaction. The merchant should: Identify the original transaction. Release the reserved or debited amount. Prevent duplicate reversals. Update the internal transaction status. Refund A Refund returns funds to the cardholder. The merchant should: Identify the related transaction where available. Credit the applicable refund amount. Prevent duplicate refund processing. Reconcile the refund against the original transaction. CashWithdrawal A CashWithdrawal represents an ATM or other cash withdrawal transaction. The merchant should: Confirm that the card supports cash withdrawal. Confirm sufficient available balance. Apply applicable withdrawal limits. Apply fraud and risk checks. Return an approval or decline decision.
• [Wallets (Position)](https://docs.miden.co/card-issuance/wallets-position.md): Flowchart
• [Overview](https://docs.miden.co/collections-and-disbursements/getting-started/overview.md): Introduction Miden Collections provides businesses with the infrastructure to accept payments from customers and manage the funds collected through Miden . With Miden Collections, you can integrate payment acceptance into your application, website, or business workflow using our supported integration options and payment methods. Funds successfully collected through Miden are processed and designated bank account Once settlement is complete, the funds become part of your available balance and can be disbursed to supported destinations. Miden Collections is organized around two core capabilities: Collections Use Collections to accept money from your customers. Depending on your integration, customers can pay using supported methods such as: Cards Bank Transfer / Virtual Accounts USSD Mobile Money Miden provides multiple ways to integrate payment acceptance, including: Hosted Checkout, Payment Links, and Direct API / Host-to-Host integrations . Disbursements Use Disbursements to send funds from your available Collection Wallet balance to your settlement account OR supported recipients. Supported payout methods include: NGN bank payouts Mobile Money payouts The Collection Wallet is not independently funded or topped up. Its balance is derived from payments collected through Miden and settled to your business. Next steps If you want to accept customer payments, continue to Collections . If you want to send funds from your available balance, continue to Disbursements . To understand the complete movement of funds through Miden, see How Miden Collections Works .
• [How Miden Collections Work](https://docs.miden.co/collections-and-disbursements/getting-started/how-miden-collections-work.md): At a high level, funds move through Miden in four stages: Collect → Process → Settle → Disburse 1. Collect a payment The flow begins when a customer makes a payment to your business. You can provide the payment experience through: Hosted Checkout — redirect customers to a Miden-hosted payment experience. Payment Links — provide customers with a link through which they can make a payment. Direct API / Host-to-Host — integrate directly with Miden APIs and build the payment experience into your application. Depending on the integration and capabilities available to your business, customers can pay using supported payment methods including Cards, Bank Transfer / Virtual Accounts, USSD, and Mobile Money. 2. Miden processes the payment Miden processes the transaction through the selected payment method and determines its payment outcome. Payment processing can be synchronous or asynchronous depending on the payment method and transaction flow. Your integration should therefore use the transaction status provided by Miden to determine the outcome of a payment. For asynchronous updates, Miden can notify your application through webhooks. A payment should only be treated as successful when its status confirms a successful outcome. 3. Successful collections are settled Successfully collected funds enter the applicable settlement process. Settlement is distinct from payment confirmation: Payment success confirms the outcome of the customer's payment. Settlement determines when the corresponding collected funds become available to your business. After settlement, the funds are credited to your Wallet and form part of your available balance. There is no additional Miden holding period after funds have been settled. Your settled balance remains accessible to your business for supported disbursements. The Collection Wallet cannot be independently funded or topped up. 4. Disburse your settled funds You can use your available Collection Wallet balance to initiate supported payouts. Funds can be disbursed to: Your settlement accounts Nigerian bank accounts Supported Mobile Money accounts A disbursement is a separate transaction from the customer payment that generated the collected funds. It has its own transaction reference, lifecycle, status, and events. Payments are stateful A payment is not simply a request and response. From the moment a customer begins a payment, the transaction moves through a lifecycle until a final outcome is reached. Depending on the payment method, the outcome may be available immediately or may require asynchronous processing. Your integration should use the payment status provided by Miden to determine the state of a transaction. See Payment Lifecycle to understand the statuses and outcomes your application should handle. Confirm payment before providing value A customer reaching a success page does not, by itself, confirm that a payment has been completed. Before delivering goods, activating a service, crediting an account, or otherwise providing value, your server should confirm the payment outcome using the transaction information provided by Miden. For asynchronous payment updates, use webhooks to receive payment events on your server. See Managing Payments and Webhooks for recommended payment-confirmation patterns. After a successful payment Successfully collected funds proceed through the applicable settlement process. Payment confirmation and settlement represent different stages: Payment confirmation determines whether the customer's payment was successful. Settlement determines when the corresponding collected funds become available in your Collection Wallet. See Settlement & Reconciliation for settlement timelines, fees, and reconciliation. Next steps Choose an Integration Compare Hosted Checkout, Payment Links, and Direct API / Host-to-Host. Payment Methods Learn how Cards, Bank Transfer / Virtual Accounts, USSD, and Mobile Money work with Miden. Payment Lifecycle Understand payment states and how your application should respond to each outcome. API Reference Use the API Reference when you need endpoint URLs, parameters, request and response schemas, or response codes.
• [Supported Countries](https://docs.miden.co/collections-and-disbursements/getting-started/supported-countries.md): Miden Collections supports payment and disbursement capabilities across supported markets. Availability varies by country, payment method, currency, and capability . A country being supported for payment collection does not necessarily mean that every payment or payout method is available in that market. Use the table below to determine the capabilities currently available for each supported country. Country availability Country Payments Bank Transfer / Virtual Account Cards USSD Mobile Money Bank Payouts Mobile Money Payouts Nigeria Supported Supported Supported Supported — Supported — Kenya Supported — — — Supported — Supported Uganda Supported — — — Supported — Supported Sierra Leone Supported — — — Supported — Supported Capability availability Payment capabilities can vary between markets because payment methods operate through different local payment networks and providers. Before building a country-specific payment experience, confirm: The country is supported by Miden. The required payment method is available in that country. The transaction currency is supported. The capability has been enabled for your business. For payout integrations, also confirm that the required recipient type and payout method are supported in the destination country. Need another market? If the country or payment method required by your integration is not listed as supported, contact Miden before implementing the payment flow.
• [Supported Currencies](https://docs.miden.co/collections-and-disbursements/getting-started/supported-currencies.md): Miden supports multiple currencies for payment collection and disbursement. Currency availability depends on the country, payment method, integration, and transaction type . Before initiating a transaction, ensure that the currency you intend to use is supported for the selected payment or payout method. Currency availability Currency Code Payments Settlement Bank Payouts Mobile Money Payouts US Dollars USD Supported Supported (Direct settlement into settlement account) — — Nigerian Naira NGN Supported Supported Supported — Kenyan Shillings UGX Supported Supported — Supported Sierra Leonean Leones SLE Supported Supported — Supported Ugandan Shillings UGX Supported Supported — Supported Note: Only currencies enabled for the relevant Miden product and your account should be submitted when initiating a transaction.
• [Collections vs Disbursements](https://docs.miden.co/collections-and-disbursements/getting-started/collections-vs-disbursements.md): Miden Collections supports two directions of money movement: Payments and Disbursements. The capability you use depends on whether your business needs to receive money from a customer or send previously collected and settled funds to a recipient . Collections Customer → Miden → Your bank account Use Payments when you need to accept money from your customers. After a successful payment completes the applicable settlement process, the collected funds are credited to your bank account Use Payments when you want to: Accept payment for a product or service. Provide customers with an online checkout experience. Generate a link through which a customer can pay. Accept payments directly through your application. Track and verify customer payments. Receive payment events through webhooks. Disbursements Available Funds → Recipient Use Disbursements when you need to send available funds from your to your settlement account or a recipient. You can initiate supported payouts to: Nigerian bank accounts Mobile Money accounts A sufficient available balance is required to complete a disbursement. Use Disbursements when you want to: Transfer collected funds to a Nigerian bank account. Send funds to a supported Mobile Money account. Manage payout beneficiaries. Track the status of a payout. Receive payout events through webhooks. Compare Payments and Disbursements Collections Disbursements Purpose Accept money Send money Direction Customer → Miden → You Available Funds → Recipient Source of funds Customer Available balance Initiated for Customer payment Recipient payout Methods Cards, Bank Transfer / Virtual Accounts, USSD, Mobile Money NGN Bank, Mobile Money Result Successfully collected funds proceed to settlement Available funds are sent to a recipient Where to start Payments documentation Disbursements documentation
• [How Collections Work](https://docs.miden.co/collections-and-disbursements/collections/introduction-to-collections/how-collections-work.md): A Miden payment begins when your application or customer initiates a payment and continues until the transaction reaches its final payment state. Although the exact customer experience varies by integration and payment method, the core processing model remains consistent: Create Payment → Customer Pays → Miden Processes → Confirm Outcome → Handle Result 1. Create the payment Your integration begins the payment flow by providing the information Miden requires to process the transaction. Depending on the integration, this may include information such as: Amount Currency Customer information Transaction reference Payment method Redirect or callback information Additional transaction metadata The exact request depends on the integration being used. 2. The customer completes the payment The customer's experience depends on your chosen integration and payment method. For example, a customer may: Enter card details. Make a transfer to a Virtual Account. Complete a USSD payment. Authorize payment through a Mobile Money flow. If you use Hosted Checkout, Miden presents the applicable payment experience to the customer. With a Direct API integration, your application has greater responsibility for controlling the payment experience. 3. Miden processes the transaction Miden processes the payment through the applicable payment channel. A transaction may reach its final outcome immediately, or additional processing may be required before the final status is known. Your application should therefore treat the payment status as the source of truth for the state of the transaction rather than assuming that a successfully submitted request means the customer has paid. 4. Determine the payment outcome Your server should determine the transaction outcome using payment information provided by Miden. Depending on the payment flow, your application can receive or retrieve payment information through: API responses Payment retrieval or verification Webhook events Webhooks are particularly important for transactions whose final outcome is determined asynchronously. Important: Do not use a browser redirect or customer-facing success message as the sole confirmation of payment. 5. Handle the result Your application should determine what to do based on the transaction's payment status. For example: Outcome Recommended action Successful Confirm the transaction and proceed with fulfilment Pending Keep the transaction open and wait for a final update Failed Do not fulfil; allow the customer to retry where appropriate Reversed Update your records to reflect the reversal Refunded Update the original transaction and refund records Use Miden's actual payment status returned for the transaction when making business decisions. See Payment Lifecycle for detailed guidance on handling payment states. 6. Settlement follows payment A successful payment can subsequently proceed to settlement. Settlement does not determine whether the customer's payment succeeded. Instead, it determines when the successfully collected funds become available to your business. This means your system should track payment status independently from settlement . See Settlement & Reconciliation for details.
• [Supported Payment Methods](https://docs.miden.co/collections-and-disbursements/collections/introduction-to-collections/supported-payment-methods.md): Miden Payments supports multiple ways for customers to complete a payment. The payment methods available for a transaction depend on the customer's market, transaction currency, your integration type, and the capabilities enabled for your business. Cards Accept card payments from customers using supported card networks. Depending on the integration, Miden can provide the customer-facing payment experience through Hosted Checkout, while eligible Direct API integrations can provide greater control over the payment flow. See Payment Methods → Cards for card-specific integration and processing details. USD - Mastercard and Visa NGN - Mastercard, Visa and Verve Bank Transfer / Virtual Accounts Accept payments by providing bank account details that customers can transfer funds to. Miden supports Virtual Account-based collection flows for use cases that require bank transfer payments. Virtual Accounts may be designed for different collection scenarios depending on the product configuration, including accounts intended for repeated use and accounts created for a specific payment or collection. See Payment Methods → Bank Transfer / Virtual Accounts for account types, transaction matching, and payment confirmation. USSD Allow eligible customers to complete payments using supported USSD payment flows. USSD availability depends on the market and payment capabilities available for the transaction. See Payment Methods → USSD for the supported payment flow and transaction handling. Mobile Money Accept payments from customers through supported Mobile Money providers. Mobile Money processing and customer authorization can vary by market and provider. See Payment Methods → Mobile Money for supported providers and payment behaviour. Payment method availability Do not assume that every payment method is available for every transaction. Before presenting a payment method to a customer, consider: Country Currency Integration type Account configuration Payment-method availability Where Miden dynamically provides available payment options through a hosted experience, only applicable methods should be presented to the customer.
• [Integration Overview](https://docs.miden.co/collections-and-disbursements/collections/choose-an-integration/integration-overview.md): Miden provides different ways to accept payments depending on how you want customers to pay and how much control you want over the payment experience. Before integrating Miden Payments, choose the approach that best matches your product, technical requirements, and desired level of control. You can accept payments using: Hosted Checkout Payment Links Direct API / Host-to-Host Compare integration options Hosted Checkout Payment Links Direct API / Host-to-Host Best for Businesses that want a ready-made online checkout Businesses that want to collect payments without building a checkout Businesses that want to build and control their payment experience Customer experience Customer completes payment on Miden's hosted checkout Customer opens a Miden-hosted payment link Payment experience is built into the merchant's application Integration effort Low Minimal Higher Frontend development Minimal Not required for the payment page Merchant-managed Backend integration Required to programmatically initialize checkout Not required for manually created payment links; API integration may be used where applicable Required Payment UI Miden-managed Miden-managed Merchant-managed Level of control Moderate Low High Typical use case Websites and applications accepting online payments Invoices, social commerce, remote collections, and quick payment requests Custom applications and payment experiences Hosted Checkout Use Hosted Checkout when you want to integrate payments into your product without building and maintaining the complete payment interface yourself. Your application initializes a payment with Miden and receives the information required to direct the customer to Miden's hosted payment experience. The customer completes payment through the available payment methods, while Miden handles the checkout interface. Hosted Checkout is a good fit when you: Have a website or application. Want to programmatically create payments. Want Miden to manage the payment interface. Want to reduce the amount of payment UI your application needs to build. Need to associate each checkout with an order or transaction in your system. Need to significantly reduce the PCI DSS scope associated with handling cardholder data. Your business remains responsible for any PCI DSS requirements applicable to its environment and integration. Choose Hosted Checkout if: you want an API-driven integration while Miden handles the customer-facing checkout. See Hosted Checkout for the complete integration flow. Payment Links Use Payment Links when you want to collect a payment by giving the customer a shareable link. The customer opens the link and completes payment through the payment experience provided by Miden. Payment Links are useful when a traditional website checkout or deeper application integration is unnecessary. Common use cases include: Sending a payment request directly to a customer. Collecting payment for an invoice. Sharing payment requests through messaging channels. Social commerce. Remote collections. Choose Payment Links if: you want a simple way to request and collect payments without building your own checkout experience. See Payment Links for details on creating, sharing, and tracking payment links. Direct API / Host-to-Host Use a Direct API / Host-to-Host integration when you want greater control over how payments are initiated and presented within your application. Your backend communicates directly with Miden's payment APIs while your application manages the customer-facing experience required for the payment flow. This approach provides greater flexibility but also places more implementation responsibility on your application. Direct API is a good fit when you: Need a custom payment experience. Want payment initiation embedded into an existing application flow. Need greater control over how payment options are presented. Have the engineering resources to manage the additional integration responsibilities. Your backend should communicate securely with Miden and must never expose secret API credentials to the customer's browser or client application. Choose Direct API / Host-to-Host if: control over the payment experience is more important than minimizing integration effort. See Direct API / Host-to-Host for implementation requirements and supported flows. Which integration should I choose? For most integrations, the decision can be simplified to: If you want to... Choose Add payments to your application while Miden manages the checkout UI Hosted Checkout Send someone a link and let them pay Payment Links Build and control the payment experience yourself Direct API / Host-to-Host The integration method determines how you connect to Miden , while the payment method determines how your customer pays . For example, Hosted Checkout is an integration method, while Card and USSD are payment methods. Do not choose an integration based solely on a payment method. First determine the customer experience and level of control you require, then confirm that the payment methods you need are supported for that integration. Next steps Continue with the guide for your chosen integration: Hosted Checkout Payment Links Direct API / Host-to-Host
• [Hosted Checkout](https://docs.miden.co/collections-and-disbursements/collections/choose-an-integration/hosted-checkout.md): Miden Hosted Checkout provides a Miden-hosted payment experience that allows you to accept payments without building the complete payment interface yourself. Your server creates a payment with Miden and directs the customer to the hosted checkout experience. The customer completes the payment using an available payment method, after which Miden redirects the customer to the return URL supplied for the transaction. Hosted Checkout is suitable when you want to integrate payment acceptance into your website or application while allowing Miden to manage the customer-facing payment page. How Hosted Checkout works A typical Hosted Checkout flow consists of the following steps: 1. Create the payment Your backend sends the transaction information required to initialize the payment with Miden. This includes information about the transaction and customer, such as the amount, currency, customer details, transaction reference, narration, and the URL to which the customer should be returned after checkout. 2. Receive the checkout information Miden creates the payment session and returns the information required to continue the hosted checkout flow. Your application uses the returned checkout link to send the customer to the Miden-hosted payment page. 3. Redirect the customer Redirect the customer's browser to the hosted checkout URL returned by Miden. From this point, the payment interaction takes place on the Miden-hosted checkout page. 4. Customer completes payment The customer selects an available payment method and follows the instructions presented during checkout. The payment methods presented to the customer depend on the methods available for the transaction and your Miden configuration. 5. Return the customer After the payment interaction is completed, the customer is returned to the redirect URL supplied when the payment was created. 6. Confirm the transaction Your backend should determine the actual outcome of the transaction using the payment information provided by Miden. Do not use the customer's return to your application as the sole basis for marking an order as paid. Hosted Checkout flow Information required to create a checkout The information required depends on the Hosted Checkout API request. Miden's hosted payment integration uses transaction information including: Information Purpose Amount Amount the customer is expected to pay Currency Currency of the payment Merchant information Identifies the business receiving the payment Customer email Identifies or contacts the customer where required Customer phone number Customer contact information used where applicable Transaction reference Associates the Miden payment with the transaction in your system Narration Describes the purpose of the payment Redirect URL Determines where the customer is returned after the checkout interaction For the exact property names, required fields, formats, validation rules, and request example, see the corresponding Hosted Checkout endpoint in the API Reference . Transaction references Assign and store a reference that allows you to associate the checkout with the corresponding order, invoice, customer transaction, or other record in your system. Maintain the relationship between your internal transaction record and the Miden payment reference returned during processing. This becomes particularly important when: Processing payment notifications. Retrieving a transaction. Investigating a payment. Reconciling collected payments. Preventing the same customer action from creating unintended duplicate business transactions. See Transaction References for reference-management guidance. Redirect the customer After successfully creating the checkout, use the checkout URL returned by Miden to redirect the customer's browser. Do not construct or modify the hosted checkout URL yourself. The customer should complete the payment on the URL provided for that payment session. Your application should also preserve enough information before redirecting the customer to identify the transaction when the customer returns. Handle the customer return Configure a redirect URL that returns the customer to an appropriate page in your application after the checkout interaction. For example, the destination might display: An order confirmation. A payment-processing message. A payment failure message. The current state of an invoice. However, the redirect is part of the customer experience; it should not be treated as authoritative proof of payment . A customer may close the browser before returning to your site, network interruptions may occur, or the final payment state may be determined independently of the browser session. Design your backend so that payment processing does not depend on the customer successfully returning to your application. Confirm the payment Before fulfilling an order, activating a service, crediting a customer, or otherwise providing value, confirm that the payment has reached the required successful state. Your backend should use Miden's server-side transaction information and payment notifications to maintain the latest state of the transaction. Where payment processing is asynchronous, keep the transaction pending in your system until its final outcome is known. See Payment Lifecycle for payment-state handling and Webhooks for asynchronous payment notifications. Handle unsuccessful or incomplete checkouts Not every checkout results in a successful payment. A customer may: Abandon the checkout. Fail to complete the selected payment method. Experience a declined or failed payment. Begin a payment whose final outcome is not immediately available. Your application should handle these situations without assuming that the absence of an immediate successful result means the same thing in every case. Use the transaction status returned by Miden to determine the appropriate action. Where appropriate, allow the customer to retry or begin another payment attempt. Next steps API Reference → Hosted Checkout Create your checkout and review the exact request and response schema. Payment Lifecycle Understand how to handle payment outcomes. Webhooks Receive payment updates on your server. Testing Test Hosted Checkout before switching to production.
• [Payment Link](https://docs.miden.co/collections-and-disbursements/collections/choose-an-integration/payment-link.md): Miden Payment Links let you request and accept customer payments through a shareable payment URL , without building a checkout experience into your application. Create a payment link for the payment you want to collect, then share the generated URL with your customer. When the customer opens the link, Miden presents the payment experience and allows them to complete the transaction using an available payment method. Payment Links are suitable for businesses that need a simple way to collect payments remotely or outside a traditional website checkout. How Payment Links work A typical Payment Link flow is: Create Payment Link → Share Link → Customer Opens Link → Customer Pays → Miden Processes Payment → Track Payment Outcome 1. Create a payment link Create a Payment Link for the payment you want to collect. The information required to create the link depends on the Payment Links API and may include transaction and customer information applicable to the payment. Once created, Miden returns a URL that can be shared with the customer. For exact request fields, validation rules, and response properties, see API Reference → Payment Links . 2. Share the payment link Send the generated URL to your customer using the channel appropriate for your business. For example, a Payment Link can be used for: Invoice payments Remote payment requests Social commerce Customer support-assisted payments Sales conducted outside a website checkout Your application should use the URL returned by Miden rather than constructing a Payment Link URL manually. 3. Customer opens the link When the customer opens the Payment Link, they are taken to the Miden-hosted payment experience. The customer can then use an available payment method to complete the transaction. Payment-method availability depends on the transaction and the capabilities enabled for your business. 4. Miden processes the payment After the customer submits the payment, Miden processes the transaction through the selected payment method. The payment then follows its applicable transaction lifecycle. The final outcome may not always be available immediately. Your systems should therefore use the payment status provided by Miden to determine whether the transaction was successful, pending, or unsuccessful. 5. Track the payment outcome Track payments made through Payment Links using Miden's transaction information and payment events. Do not treat a customer-facing success screen as the authoritative confirmation that payment has been completed. If your business automatically provides value after payment—for example, updating an invoice, activating a service, or fulfilling an order—base that action on the confirmed transaction status. See Payment Lifecycle and Webhooks for transaction-state and event-handling guidance. Payment Links flow When to use Payment Links Payment Links work well when you need to collect a payment but do not need to embed payment initiation into a customer-facing application flow. Consider Payment Links when you want to: Request payment from a specific customer. Collect payment for an invoice or order. Send customers a payment request through messaging or other communication channels. Accept payments without building a dedicated checkout page. Start accepting payments with minimal integration effort. Example Suppose your business receives an order through a sales representative. Instead of requiring the customer to visit your website and find the order again, you can create a Payment Link for the transaction and send the link directly to the customer. The customer opens the link, completes payment through Miden, and your system can subsequently track the payment outcome. Track each payment Maintain the transaction information required to associate a Payment Link payment with the corresponding record in your system. For example, you may need to associate the payment with: An order An invoice A customer A subscription or service An internal transaction reference This allows your system to correctly identify the business transaction when payment updates are received. See Transaction References for reference-management guidance. Handle incomplete payments Creating or opening a Payment Link does not mean that a payment has been completed. A customer may open a link without paying, abandon the payment flow, encounter a failed transaction, or initiate a payment whose final outcome is still pending. Your business logic should therefore be driven by the payment transaction status , not by link activity. Do not mark an invoice or order as paid simply because: The Payment Link was created. The customer opened the link. The customer reached a particular page in the payment experience. Confirm the transaction outcome before providing value. Next steps API Reference → Payment Links Review the endpoints and exact request and response schemas for creating and managing Payment Links. Payment Lifecycle Understand how to handle pending, successful, and unsuccessful transactions. Webhooks Receive asynchronous payment updates. Transaction References Associate Miden payments with transactions in your system. Testing Test your Payment Link flow before accepting production payments.
• [Direct API/Host-to-Host](https://docs.miden.co/collections-and-disbursements/collections/choose-an-integration/direct-api-host-to-host.md): Direct API, also referred to as Host-to-Host , allows you to integrate Miden payment capabilities directly into your application. Instead of redirecting the customer to a Miden-hosted checkout, your application manages the payment experience while your backend communicates with Miden APIs to initiate and manage the transaction. This integration provides greater control over your customer experience and payment workflow, but requires more implementation responsibility than Hosted Checkout or Payment Links. How Direct API works A typical Direct API payment flow is: Collect Payment Information → Create Payment → Process Payment → Receive Status → Confirm Outcome → Fulfil 1. Your application starts the payment The customer begins the payment within your website or application. Your application presents the payment options available for the transaction and collects the information required for the selected payment method. The exact customer interaction depends on the payment method. 2. Your backend sends the payment request Your server sends the payment request directly to Miden. Protected Miden API requests require an OAuth 2.0 access token. Obtain the token using your Client ID and Client Secret and include it in subsequent requests: Authorization: Bearer <access_token> Keep your Client ID, Client Secret, and other secret credentials exclusively in your server-side environment. See Authentication for the complete authentication flow. 3. Miden processes the payment Miden receives the request and processes the transaction through the applicable payment method. Depending on the payment method, additional customer action may be required before the payment can complete. Your application should follow the instructions and transaction state returned for the payment rather than assuming every payment uses the same interaction. 4. Track the transaction status The response to a payment request represents the state of the transaction at that point in time. Some transactions may reach a final state immediately, while others may remain pending while additional processing or customer action takes place. Your system should persist the transaction reference and current payment status so that subsequent updates can be associated with the correct transaction. 5. Receive asynchronous updates Where the payment outcome changes asynchronously, Miden can send transaction events to your configured webhook endpoint. Your webhook handler should update the corresponding transaction in your system without creating duplicate business actions when the same event is received more than once. See Webhooks for event delivery and verification. 6. Confirm the final outcome Before providing value to the customer, confirm that the payment has reached the required successful state. Use server-side transaction information to make fulfilment decisions. For example, only after payment success has been confirmed should your application: Mark an order as paid. Ddebit a customer balance. Activate a paid service. Release digital goods. Trigger downstream fulfilment. See Payment Lifecycle for guidance on transaction states. Direct API flow The exact interaction varies by payment method. See the relevant Payment Method guide for method-specific flows. Your responsibilities Direct API gives you greater control, which also means your application assumes more responsibility for the payment experience. Customer experience Your application controls how the payment journey is presented to the customer. This includes: Presenting applicable payment methods. Collecting the information required for the selected method. Displaying processing states. Handling successful and unsuccessful outcomes. Providing retry experiences where appropriate. Server-side integration Payment requests should be initiated from a trusted backend environment. Your backend is responsible for: Authenticating with Miden. Creating payment requests. Securely managing credentials. Persisting transaction references. Tracking transaction statuses. Receiving webhook events. Confirming payment before fulfilment. Transaction state Do not design the integration around the assumption that every payment completes within a single HTTP request. Your application must be capable of maintaining a transaction while its state changes over time. Handle payment responses correctly An HTTP success response means that Miden successfully handled the API request at the HTTP level. It should not automatically be interpreted as proof that the underlying payment was successful. Your integration should evaluate the transaction information returned by Miden to determine the payment outcome. This distinction is particularly important because Miden APIs expose both HTTP status codes and application response codes . Use the applicable transaction status and response information to determine the business outcome of the request. See Response Codes and Payment Lifecycle for details. Transaction references Maintain a reliable mapping between your internal transaction and the identifiers associated with the Miden payment. Your system should be able to use these references to: Retrieve a payment. Associate webhook events with the correct transaction. Investigate payment issues. Reconcile transactions. Prevent unintended duplicate processing. See Transaction References for reference-management guidance. Build for retries and duplicate processing Network failures create an important problem for direct integrations. For example, your application may send a payment request successfully but lose connectivity before receiving Miden's response. In this situation, blindly creating another payment can result in unintended duplicate processing. Where supported by the relevant Miden endpoint, use the documented idempotency mechanism and transaction references to make retries safe. Do not invent your own assumptions about whether a failed HTTP connection means the underlying payment request was not processed. See Idempotency for the supported implementation pattern. Security considerations A Direct API integration should be treated as a server-to-server payment integration. At minimum: Keep API credentials server-side. Use HTTPS for all production communication. Validate input before submitting payment requests. Do not log secrets or sensitive payment information. Verify webhook authenticity. Store transaction references and statuses. Make transaction processing idempotent. Confirm payment server-side before fulfilment. Restrict production credentials to the systems that require them. Payment-method-specific security requirements may also apply. See the relevant Payment Method guide before implementing the corresponding flow. When to use Direct API Direct API / Host-to-Host is best suited to businesses that: Want to build their own payment experience. Need greater control over payment initiation. Want payments deeply integrated into an existing product workflow. Need to control how payment methods are presented. Have backend infrastructure capable of managing payment state and asynchronous events. Can implement the additional security and reliability requirements of a direct integration. If you primarily want Miden to manage the payment interface, use Hosted Checkout instead. If you simply need to send customers a URL through which they can pay, use Payment Links . Next steps Payment Methods Understand the payment-method-specific behaviour required by your Direct API integration. API Reference → Payments Review endpoints, request fields, response schemas, and application response codes. Payment Lifecycle Design your application to correctly handle payment states. Webhooks Receive asynchronous transaction updates. Idempotency Implement safe payment-request retries. Testing Validate successful, pending, and failed payment scenarios before going live.
• [Overview](https://docs.miden.co/collections-and-disbursements/collections/payment-methods/overview.md): Payment methods determine how your customers pay when making a payment through Miden. Miden supports multiple payment methods to accommodate different customer preferences and markets: Cards Bank Transfer / Virtual Accounts USSD Mobile Money The payment methods available for a transaction depend on factors such as: the customer's market, transaction currency, your integration type, and the capabilities enabled for your Miden account. Choose a payment method Payment method Customer pays using Best suited for Cards A supported debit or credit card Online and in-app payments Bank Transfer / Virtual Accounts A bank transfer to account details provided for collection Account-to-account payments and transfer-based collections. NGN only USSD A USSD session with a supported bank/payment provider Customers who prefer bank payments without a card. NGN only Mobile Money A supported Mobile Money account Markets where Mobile Money is commonly used. Payment method availability Not every payment method is necessarily available for every transaction. Before presenting a payment option, consider: Country Currency Integration type Account configuration Payment-method availability
• [Cards](https://docs.miden.co/collections-and-disbursements/collections/payment-methods/cards.md): Miden enables customers to make payments using supported debit and credit cards. The customer provides their card details and completes any authentication required for the transaction before Miden processes the payment. How card payments work 1. Customer selects Card During checkout, the customer selects Card as their preferred payment method and provides the required card details. For NGN card payments, the customer is also required to enter their 4-digit card PIN as part of the checkout flow. 2. Customer completes authentication Where additional authentication is required, such as 3D Secure (3DS) or OTP , the customer completes the authentication step presented during checkout. The authentication required may vary depending on the card, issuer, and transaction. 3. Miden processes the payment Once the required card information and authentication have been completed, Miden processes the transaction and determines the payment outcome. A successfully completed card payment is treated as a completed collection and proceeds to settlement. Payment confirmation Completing the card details, PIN, OTP, or 3DS authentication does not, by itself, confirm that the payment was successful. You should use the payment status or event provided by Miden to confirm the transaction outcome before fulfilling the payment.
• [Bank Transfer / Virtual Accounts](https://docs.miden.co/collections-and-disbursements/collections/payment-methods/bank-transfer-virtual-accounts.md): Miden enables customers to pay by bank transfer using Virtual Accounts . During checkout, when a customer selects Bank Transfer , Miden creates a Dynamic Virtual Account for the payment and presents the account details the customer needs to complete the transfer. How Bank Transfer payments work 1. Customer selects Bank Transfer The customer chooses Bank Transfer as their payment method during checkout. 2. Miden creates a Dynamic Virtual Account Miden automatically generates a Dynamic Virtual Account for the checkout. The account details presented to the customer include the information required to make the transfer, such as: Account number Account name Bank name The merchant does not need to create the Dynamic Virtual Account separately. 3. Customer makes the transfer The customer transfers the required amount to the account details provided using their preferred banking channel. 4. Miden identifies the payment When the transfer is received, Miden detects the inflow and associates it with the corresponding checkout transaction. This allows the incoming transfer to be matched to the payment without requiring the merchant to manually identify the customer's bank transfer. 5. Payment is confirmed Once the transfer has been successfully identified and processed, Miden updates the payment with its resulting status. Use the confirmed payment status before fulfilling the customer's transaction. Do not treat account creation as payment Successfully creating a Virtual Account means that account details are available for collection. It does not mean that the customer has paid. Only update the customer's financial obligation after Miden confirms receipt of the corresponding payment. This distinction is particularly important for invoice, wallet-crediting, and order-fulfilment systems. Reconciliation Store the identifiers associated with the Virtual Account and incoming transaction. These identifiers allow you to associate an incoming transfer with the appropriate: Customer Order Invoice Collection Internal transaction record See Settlement & Reconciliation for downstream reconciliation guidance.
• [USSD](https://docs.miden.co/collections-and-disbursements/collections/payment-methods/ussd.md): Miden supports USSD as a payment method for eligible transactions. USSD allows customers to initiate or authorize a payment through a supported banking or payment-provider USSD channel without entering card details. How USSD payments work 1. Customer selects USSD During checkout, the customer selects USSD as their preferred payment method. 2. Customer selects their bank The customer chooses their bank from the dropdown list of supported NGN banks presented on the checkout. 3. Miden provides the USSD code Based on the selected bank, Miden generates and displays the USSD code required to complete the payment. The customer should dial the code using the phone number registered with their bank. 4. Customer completes the USSD payment The customer leaves the checkout interaction to dial the provided USSD code on their phone. They follow their bank's USSD prompts to authorize and complete the payment. 5. Miden detects the payment Once the payment is completed through the customer's bank, Miden detects the transaction and updates the corresponding payment. 6. Payment is confirmed The resulting payment status or event indicates the outcome of the transaction. Your application should use the confirmed payment status before treating the transaction as successfully paid. Important The customer's completion of the USSD prompts does not, by itself, confirm a successful payment. Wait for Miden to confirm the payment outcome before fulfilling the transaction. Availability USSD payments are available through supported NGN banks presented during checkout. The banks available to a customer are determined by the options currently supported by Miden. Customer experience When offering USSD: Display payment instructions clearly. Keep the customer informed while payment confirmation is pending. Do not mark the transaction as paid before confirmation. Provide an appropriate retry or alternative payment option if the transaction fails or cannot be completed. See Pending Payments for handling transactions whose final outcome is not immediately available.
• [Mobile Money](https://docs.miden.co/collections-and-disbursements/collections/payment-methods/mobile-money.md): Miden enables customers to pay using Mobile Money (MoMo) through supported providers in eligible countries. During checkout, the customer selects Mobile Money, enters their mobile number, and chooses an available provider. Miden then initiates a payment prompt to the customer's phone for authorization. How Mobile Money payments work 1. Customer selects Mobile Money During checkout, the customer selects Mobile Money (MoMo) as their preferred payment method. The customer selects their country and enters the mobile number associated with their Mobile Money account. 2. Customer selects a provider Miden displays the Mobile Money providers available for the selected country. The customer selects their provider and proceeds with the payment. 3. Miden sends a payment prompt When the customer selects Pay Now , Miden initiates a Mobile Money payment prompt to the provided phone number. The customer follows the prompt on their phone to authorize the transaction using their Mobile Money PIN. 4. Alternative authorization If the customer does not receive the payment prompt, Miden displays alternative instructions for the selected provider where available. These may include a provider-specific USSD code and the steps required to locate and approve the pending transaction. The customer should follow the instructions displayed on the checkout, as the authorization process varies by provider. 5. Customer authorizes the payment The customer approves the transaction through their Mobile Money provider. Completing the authorization allows the provider to process the payment. 6. Miden confirms the payment Miden detects the outcome of the Mobile Money transaction and updates the corresponding payment. Use the resulting payment status or event to confirm that the payment was successful before fulfilling the transaction. Provider availability The Mobile Money providers presented during checkout depend on the selected country. Country Currency Supported provider(s) Kenya KES M-PESA Uganda UGX Airtel, MTN Sierra Leone SLE Orange Only providers presented by Miden for the selected country should be considered available for the transaction. Payment prompts and alternative authorization The primary Mobile Money experience is a payment prompt sent to the customer's phone. If a prompt is not received, the checkout may provide an alternative provider-specific authorization flow. Because these instructions vary between providers, customers should follow the instructions displayed by Miden rather than relying on a fixed USSD sequence. Important Selecting Pay Now , receiving a payment prompt, or clicking I have Approved does not by itself confirm that the payment was successful. The transaction should only be treated as paid after Miden confirms the successful payment outcome.
• [Understanding Payment Statuses](https://docs.miden.co/collections-and-disbursements/collections/payment-lifecycle/understanding-payment-statuses.md): Overview Every payment processed through Miden moves through a defined lifecycle that represents its current processing state. A payment can follow one of these primary paths: Pending → Successful → Reversed Pending → Successful → Refunded Pending → Failed For successful payments, whether a payment can be reversed or refunded depends on whether settlement has occurred. Status Meaning Pending The payment has been initiated, but a final outcome has not yet been determined. Successful Miden has confirmed that the payment was completed successfully. Failed The payment could not be completed successfully. Reversed A successful payment was returned to the customer before settlement to the merchant. Refunded A successful, settled payment was returned to the customer by the merchant. Use the payment status provided by Miden as the source of truth when determining the outcome of a transaction. Reversal vs Refund Both reversals and refunds return funds to the customer. The difference is determined by whether settlement to the merchant has occurred. Before Settlement → Reversal → Funds returned to Customer After Settlement → Refund → Funds returned to Customer A successful payment that has not yet been settled to the merchant can be reversed. Once the payment has already been settled to the merchant, the merchant must use a refund to return the funds to the customer.
• [Pending Payments](https://docs.miden.co/collections-and-disbursements/collections/payment-lifecycle/pending-payments.md): Overview A payment is Pending when it has been initiated but Miden has not yet determined its final outcome. This may occur while the customer completes an authorization step or while Miden waits for confirmation from the underlying payment channel. A pending payment can transition to: Pending → Successful or Pending → Failed Handling pending payments Do not fulfil a transaction while its payment remains pending. For payment methods that complete asynchronously, wait for the resulting payment event or retrieve the payment status to determine the final outcome. Do not assume that a delayed response means the payment failed. Confirm the transaction status before initiating another payment attempt.
• [Successful Payments](https://docs.miden.co/collections-and-disbursements/collections/payment-lifecycle/successful-payments.md): Overview A payment is Successful when Miden has confirmed that the transaction was completed successfully. At this point, the transaction is considered a completed collection. What can happen next depends on settlement. Before settlement If the payment has not yet been settled to the merchant, it can be reversed . Successful → Reversed After settlement Once the payment has been settled to the merchant, funds can be returned using a refund . Successful → Refunded Merchants should rely on Miden's confirmed payment status before fulfilling the associated transaction.
• [Failed Payments](https://docs.miden.co/collections-and-disbursements/collections/payment-lifecycle/failed-payments.md): Overview A payment is Failed when the transaction cannot be completed successfully. Pending → Failed A payment may fail because the transaction was declined, required customer authorization was not completed, payment information was invalid, or the underlying payment channel could not complete the transaction. Handling failed payments Do not fulfil a transaction associated with a failed payment. Where available, use the response information returned by Miden to understand the reason for the failure and determine the appropriate customer experience. A failed payment is a final outcome. If the customer wants to try again, initiate a new payment attempt.
• [Reversals](https://docs.miden.co/collections-and-disbursements/collections/payment-lifecycle/reversals.md): Overview A reversal occurs when a successful payment is returned to the customer before the funds have been settled to the merchant. Successful → Reversed Reversals apply only while a successful collection remains unsettled. When reversals happen A payment may be reversed when: The payment was successfully completed. The funds have not yet been settled to the merchant. The transaction needs to be returned to the customer before settlement. Once the payment has been settled to the merchant, a reversal no longer applies. Returning the funds to the customer requires a refund . Why reversals happen Reversals can occur when a payment cannot proceed through its normal processing or settlement flow after it has initially been successful. Common reasons may include: The transaction is subsequently declined or rejected during downstream processing. A processing or network issue prevents the transaction from completing as expected. The payment is cancelled before settlement. The payment cannot be settled and must be returned. The underlying payment provider or financial institution reverses the transaction. The exact reason depends on the payment method and circumstances surrounding the transaction.
• [Refunds](https://docs.miden.co/collections-and-disbursements/collections/payment-lifecycle/refunds.md): A refund returns funds to the customer after a successful payment has already been settled to the merchant. Successful → Refunded Refunds apply when funds from the original payment have already been settled and subsequently need to be returned to the customer. When refunds happen A refund may be initiated when: The original payment was successful. The funds have already been settled to the merchant. Some or all of the payment needs to be returned to the customer. If the payment has not yet been settled, a refund does not apply. The transaction may instead be reversed . Why refunds happen Refunds are typically initiated by the merchant for business or customer-service reasons after a payment has been completed and settled. Common reasons may include: The customer cancels an order or service. The merchant is unable to fulfil the order. Goods are returned by the customer. The customer was charged incorrectly. A duplicate payment needs to be returned. The merchant and customer agree that the payment should be returned. The reason for a refund depends on the circumstances of the original transaction. After a refund The refund must be processed through api or via your Miden dashboard. Use the resulting refund status or event to determine when the refund has been completed. Once completed, the refunded amount is returned to the customer and the transaction reflects the applicable refund outcome. For instructions on initiating and tracking refunds, see Managing Payments → Refund a Payment .
• [Retrieve & Verify a Payment](https://docs.miden.co/collections-and-disbursements/collections/managing-payments/retrieve-and-verify-a-payment.md): Retrieve a payment to view its transaction details and confirm its current status. Use the payment retrieval endpoint when your application needs to check the outcome of an existing payment, recover its state after an interrupted flow, or confirm that a payment was successful before fulfilment. When to retrieve a payment Retrieve a payment when you need to: Check the current status of a payment. View the details of an existing transaction. Confirm a payment before fulfilling an order or providing a service. Resolve a transaction that remains pending in your application. Recover the payment state after a timeout or interrupted request. Reconcile a payment with the corresponding transaction in your system. Verify the payment outcome The payment status returned by Miden should be used to determine the current outcome of the transaction. Do not rely solely on a checkout redirect, customer-facing success screen, or frontend response as confirmation that payment was successful. Customer Completes Payment → Retrieve Payment → Check Status → Confirm Payment → Fulfil Before fulfilment, confirm that the payment details match the transaction expected by your system, including the: Transaction reference Amount Currency Payment status If the payment remains Pending , do not assume that it has failed. Wait for the applicable payment event or retrieve the payment again to obtain its latest status.
• [Refund a Payment](https://docs.miden.co/collections-and-disbursements/collections/managing-payments/refund-a-payment.md): Refund a successfully settled payment when some or all of the funds need to be returned to the customer. Miden supports both full and partial refunds . Merchants can initiate refunds through the Refund API or directly from the Miden Dashboard . Refunds apply to payments that have already been settled to the merchant. For more information about when refunds apply, see Payment Lifecycle → Refunds . Full and Partial Refunds Depending on the amount that needs to be returned, a merchant can issue: Full refund — Returns the full eligible amount of the original payment to the customer. Partial refund — Returns only a specified portion of the original payment to the customer. The refund amount cannot exceed the eligible refundable amount of the original transaction. Refund via API Use the Refund API when refunds need to be initiated programmatically from your application or backend. A typical flow is: Identify Payment → Specify Refund Amount → Initiate Refund → Miden Processes Refund → Track Refund Outcome → Customer Receives Funds Use the original transaction information when submitting the refund request to ensure the refund is associated with the correct payment. See API Reference → Payments → Refund Payment for the endpoint, request parameters, and response. Refund via Dashboard Merchants can also initiate a full or partial refund directly from the Miden Dashboard. This is useful for refunds handled manually by operations, support, or other authorized users without requiring an API request. Locate the applicable transaction on the dashboard, select the refund action, and specify the amount to be returned. After initiating a refund A successful refund request confirms that Miden has accepted the request for processing. It does not necessarily mean the funds have already been returned to the customer. Use the resulting refund status or event to determine the final outcome. Once successfully completed, the applicable refund amount is returned to the customer through the relevant payment channel. Important Before initiating a refund: Confirm that the original payment was successful and has been settled. Confirm that the correct transaction and refund amount have been selected. Ensure the refund amount does not exceed the eligible refundable amount. Do not treat submission of the refund request as confirmation that the refund has completed. Track the resulting status or event until the refund reaches its final outcome. If the original payment has not yet been settled, a reversal , rather than a refund, may apply.
• [Transaction References](https://docs.miden.co/collections-and-disbursements/collections/managing-payments/transaction-references.md): Transaction references are unique identifiers used to identify and track payments across Miden and for your application. They allow you to associate a payment processed by Miden with the corresponding order, invoice, customer, or transaction in your own system. Miden Transaction Reference Miden assigns a transaction reference to identify the payment within Miden. Store this reference alongside your own transaction reference, if it differs from Miden's. Together, these identifiers allow both your system and Miden to identify the same transaction during payment tracking, reconciliation, and investigation. Store payment references Persist the references associated with each payment in your system. You may need them when: Retrieving a payment. Matching payment events to transactions. Processing refunds. Reconciling collections. Investigating transaction issues. Escalating transaction issues to the Miden team A typical mapping might look like: Your Order Your Reference Miden Transaction Reference ORD-10482 ORDER-20260824-001 90aa7dc3018c4a81b3ed4a90ad96b90 Reference best practices Store both your reference and Miden's transaction reference. Keep references immutable once associated with a payment. Use references when correlating API responses and payment events with your internal records. Important: A transaction reference identifies a payment; it does not indicate whether the payment was successful. Always use the payment status to determine the transaction outcome.
• [Overview](https://docs.miden.co/collections-and-disbursements/collections/webhooks-1/overview-1.md): Webhooks allow Miden to send real-time transaction updates to your application when payment events occur. Instead of repeatedly querying Miden for a transaction's latest status, your application can receive an HTTP POST request whenever a relevant event is generated. Webhooks are particularly useful for payment flows that complete asynchronously, such as Bank Transfer , USSD , and Mobile Money . How webhooks work A typical webhook flow is: Payment Event Occurs → Miden Creates Event → Miden Sends HTTP POST → Merchant Processes Event → Merchant Updates Transaction Miden sends the event to the webhook URL configured for your account. Your application should use the event information to identify the affected transaction and update the corresponding record in your system. Webhook structure Miden webhook events follow a common structure: { "eventId": "d4a79237-c630-4a40-b7ac-075a56755f1b", "eventClass": "Collections", "eventTime": "2025-08-04T22:48:08.876017Z", "eventType": "collection.cards", "data": {} } Field Description eventId Unique identifier for the webhook event eventClass High-level category of the event eventTime Time the event occurred eventType Specific event generated by Miden data Event-specific transaction information The contents of data depend on the event type. Use webhooks with transaction retrieval Webhooks provide asynchronous updates, while the payment retrieval API allows your application to request the current state of a transaction directly from Miden. For payment-critical actions, your application can use both mechanisms together. Important: A webhook should update your application's knowledge of the transaction. Your business logic should still rely on the payment status contained in the event or retrieved from Miden—not simply on receipt of the webhook itself.
• [Payment Events](https://docs.miden.co/collections-and-disbursements/collections/webhooks-1/payment-events.md): Miden sends payment events when activity occurs on supported collection channels. The eventType identifies the type of event being delivered, while the data object contains the information associated with the transaction. Collection events Examples of payment collection events include: Event Type Description collection.cards Card collection event collection.virtual-accounts Virtual Account / Bank Transfer collection event Additional event types may be available depending on the Miden products and payment methods enabled for your account. Card collection event A card collection webhook includes information about the completed card transaction. Example: { "eventId": "d4a79237-c630-4a40-b7ac-075a56755f1b", "eventClass": "Collections", "eventTime": "2025-08-04T22:48:08.876017Z", "eventType": "collection.cards", "data": { "eventId": "d4a79237-c630-4a40-b7ac-075a56755f1b", "eventClass": "Collections", "eventType": "collection.cards", "transactionAmount": 5070.0, "settledAmount": 5019.3, "transactionReference": "90aa7dc3018c4a81b3ed4a90ad96b901", "merchantReference": "a499034314cc49e7bfe96a9fd806e948", "channel": "Cards", "narration": "Test Transaction", "status": "Successful", "transactionType": "Collections", "currency": "USD", "requestDate": "2025-08-04T22:48:08.876017Z" } } Virtual Account collection event For Bank Transfer collections, Miden sends a Virtual Account event when the incoming payment is detected. Example: { "eventId": "d4a79237-c630-4a40-b7ac-075a56755f1b", "eventClass": "Collections", "eventTime": "2025-08-04T22:48:08.876017Z", "eventType": "collection.virtual-accounts", "data": { "virtualAccountNumber": "6563004789", "transactionAmount": 5070.0, "settledAmount": 5019.3, "transactionReference": "90aa7dc3018c4a81b3ed4a90ad96b901", "merchantReference": "a499034314cc49e7bfe96a9fd806e948", "sourceAccountNumber": "1234567890", "sourceAccountName": "Test User", "sourceBankName": "Test Bank", "channel": "VirtualAccount", "status": "Successful", "transactionType": "VirtualAccountCollection", "currency": "NGN", "requestDate": "2025-08-04T22:48:08.876017Z" } } Processing payment events When a payment event is received: Identify the event using eventId . Identify the transaction using transactionReference and/or merchantReference . Check the transaction status . Update the corresponding payment in your system. Trigger fulfilment only when the payment state permits it.
• [Configure Your Webhook](https://docs.miden.co/collections-and-disbursements/collections/webhooks-1/configure-your-webhook.md): Configure a webhook URL to receive payment events from Miden. Your webhook endpoint should be a server-side HTTPS endpoint that can accept HTTP POST requests from Miden. Webhook endpoint A webhook URL typically looks like: https://api.example.com/webhooks/miden When an applicable event occurs, Miden sends the webhook payload to the URL configured for your account. Endpoint requirements Your webhook endpoint should: Be publicly reachable from the internet. Use HTTPS in production. Accept HTTP POST requests. Accept JSON request bodies. Process events server-side. Return a successful HTTP response after the event has been accepted. Processing incoming events When your endpoint receives an event: Read the webhook payload. Verify the webhook authenticity using Miden's supported verification mechanism. Check whether the eventId has already been processed. Identify the corresponding transaction. Update your internal payment record. Return the expected successful HTTP response. Perform long-running business operations asynchronously where possible rather than delaying the webhook response. Separate environments Use separate webhook endpoints or configurations for your test and production environments. For example: Sandbox https://sandbox-api.example.com/webhooks/miden Production https://api.example.com/webhooks/miden This helps prevent test events from being processed as live transactions. Before going live Before accepting production payments, confirm that your webhook endpoint: Is reachable over HTTPS. Can process Miden's JSON payloads. Verifies incoming webhook authenticity. Handles duplicate events safely. Maps events to the correct transaction. Records processing failures for investigation.
• [Sandbox Environment](https://docs.miden.co/collections-and-disbursements/collections/testing/sandbox-environment.md): The Miden Sandbox environment allows you to build and test your payment integration without processing real customer funds. Use Sandbox throughout development to validate your checkout integration, payment methods, transaction handling, webhooks, and payment outcomes before moving to production. What you can test Depending on the payment methods enabled for your integration, Sandbox can be used to test: Hosted Checkout and API-based payment flows. Card payments and authentication flows. Successful and failed payment scenarios. Payment statuses and transaction retrieval. Webhook delivery and event handling. Other supported test payment methods. Test data Sandbox transactions must use the test credentials and payment details provided in this section. Do not use real customer card details or other live payment credentials when testing your integration. Important: Sandbox transactions are simulations. No real funds are moved, and Sandbox transaction results should not be treated as production transactions. Before going live Before switching to production, ensure that your integration can: Process successful and failed payment scenarios correctly. Handle required customer authentication. Retrieve and verify payment outcomes. Process webhook events safely. Prevent duplicate processing. Handle pending or delayed payment outcomes appropriately. Once testing is complete, replace your Sandbox credentials and configuration with the corresponding production configuration.
• [Test Cards](https://docs.miden.co/collections-and-disbursements/collections/testing/test-cards.md): Miden provides test card details that you can use to simulate card payments without using real cards or moving real funds. Use the cards below only in the Sandbox environment . Test cards can be used to validate: Successful card payments. Declined or failed payments. PIN and OTP authentication flows. Your application's handling of different transaction outcomes. USD Test Cards Approved Transaction Use this card to simulate an approved USD card payment. Field Value PAN 4440 0000 0990 0010 Expiry 01/39 CVV 100 Expected Outcome Approved Declined Transaction Use this card to simulate a declined USD card payment. Field Value PAN 5123 4500 0000 0008 Expiry 05/39 CVV 100 Expected Outcome Declined NGN Test Cards NGN card payment testing may require PIN and OTP authentication as part of the checkout flow. Successful Transaction Field Value PAN 5061 0502 5475 6707 864 Expiry 06/26 CVV 111 PIN 1111 OTP 123456 Expected Outcome Successful Failed Transaction — Insufficient Funds Field Value PAN 5060 9905 8000 0000 390 Expiry 03/50 CVV 111 PIN 1111 OTP 123456 Expected Outcome Failed — Insufficient Funds Additional API Test Cards The following cards can be used for applicable API card-payment testing. PAN Expiry CVV 4000000000002503 12/36 100 4105400029297734 01/28 854 5078729011516523 01/31 250 For integrations where the expiry date is supplied as separate fields, provide the month and four-digit year. Example: { "expirationMonth": "12", "expirationYear": "2036", "number": "4000000000002503", "cvv": "100" } Important Test cards are provided strictly for Sandbox testing. Do not use these card details in the production environment, and do not use real cardholder information when testing your integration.
• [Overview](https://docs.miden.co/collections-and-disbursements/disbursements/introduction-to-disbursements/overview.md): Miden Disbursements enables you to send money across supported fiat and stablecoin payout routes. Disbursements are currently supported for: NGN KES UGX SLE You can use Disbursements for customer payouts, vendor and supplier payments, marketplace payouts, reimbursements, and other business payments. Payouts can be initiated from the Miden Dashboard or through the applicable Disbursement API .
• [How Disbursements Work](https://docs.miden.co/collections-and-disbursements/disbursements/introduction-to-disbursements/how-disbursements-work.md): A disbursement sends funds to a recipient using the payout route available for the selected currency. Disbursement flow Select Wallet → Enter Recipient Details → Enter Amount → Initiate Payout → Miden Processes Payout → Confirm Outcome 1. Select the source currency Select the currency you want to send. 2. Provide payout details Enter the recipient information required for the selected currency and payout method. The required details differ between bank , mobile money , and stablecoin payouts. 3. Initiate the payout Enter the amount and narration, then submit the disbursement. Miden validates the request and processes it through the applicable payout route. 4. Confirm the outcome Use the resulting transaction status or event to determine the final outcome of the disbursement. Important: A successfully submitted request does not necessarily mean the recipient has received the funds. Use Miden's final transaction status as the source of truth.
• [Supported Countries & Currencies](https://docs.miden.co/collections-and-disbursements/disbursements/introduction-to-disbursements/supported-countries-and-currencies.md): Miden supports fiat and stablecoin disbursements across the following currencies: Currency Market Payout Type NGN Nigeria Bank Account KES Kenya Mobile Money UGX Uganda Mobile Money SLE Sierra Leone Mobile Money The information required to complete a payout depends on the selected currency and payout type.
• [Supported Payout Methods](https://docs.miden.co/collections-and-disbursements/disbursements/introduction-to-disbursements/supported-payout-methods.md): miden supports three primary payout methods: bank account and mobile money Bank Account Available for NGN payouts . Provide: Bank name Account number Amount Narration Miden processes the payout to the specified Nigerian bank account. Mobile Money Available for KES, UGX, and SLE payouts . Provide: Amount Phone number Provider Narration The available provider depends on the selected currency and market. Miden sends the funds to the mobile money account associated with the provided phone number.
• [Disbursement Lifecycle](https://docs.miden.co/collections-and-disbursements/disbursements/introduction-to-disbursements/disbursement-lifecycle.md): Every disbursement progresses from initiation to a final transaction outcome. At a high level: Initiate Payout → Miden Processes Payout → Final Outcome A payout may complete immediately or remain in processing while Miden waits for confirmation from the underlying payout provider or network. Successful payouts When Miden confirms that the payout was processed successfully, the disbursement is considered completed. Failed payouts If the payout cannot be completed, the transaction returns a failed outcome. Where available, use the response information provided by Miden to determine the reason for the failure. Confirming payout status Always use the transaction status returned by Miden as the source of truth. For asynchronous payouts, wait for the resulting status or webhook event before treating the disbursement as successfully completed.
• [NGN Bank Payouts](https://docs.miden.co/collections-and-disbursements/disbursements/payout-methods/ngn-bank-payouts.md): NGN Bank Payouts allow you to send funds directly to a recipient's Nigerian bank account. To complete an NGN payout, select the recipient's bank, provide and resolve their account number, enter the payout amount and narration, then initiate the transaction. Payouts can be initiated from the Miden Dashboard or programmatically through the Disbursement API . How NGN Bank Payouts Work 1. Select the recipient's bank Select the recipient's bank from the list of supported Nigerian banks available through Miden. For API integrations, use the supported bank information provided by Miden when resolving the account and initiating the payout. 2. Enter the account number Provide the recipient's bank account number. The bank and account number together identify the destination account for the payout. 3. Resolve the account Miden resolves the account number against the selected bank and returns the corresponding account information. Confirm that the resolved account details belong to the intended recipient before continuing. Account resolution verifies the destination account only. It does not initiate a payout or move funds. 4. Enter the payout details Provide the transaction details required to complete the payout: Amount — The amount to send in NGN. Narration — A description or reference for the payout. Review the recipient and transaction details before submitting the payout. 5. Initiate the payout Once the recipient's account has been confirmed and the payout details have been provided, initiate the transaction. You can initiate an NGN bank payout: From the Miden Dashboard . Programmatically through the applicable Disbursement API . For API-based payouts, use the request fields and validation requirements documented in API Reference → Disbursements . 6. Miden processes the payout Miden validates the payout request and routes the transaction to the recipient's bank account. The transaction is then updated with the resulting payout status. 7. Confirm the outcome Use the transaction status or resulting webhook event provided by Miden to determine the final payout outcome. Do not treat successful submission of the payout request as confirmation that the recipient has received the funds. For information about payout statuses and outcomes, see Disbursement Lifecycle . Important Confirm the resolved account details before initiating the payout. Use the supported bank information provided by Miden rather than maintaining a permanently hard-coded bank list. Ensure the payout amount and narration are correct before submitting the transaction. Use Miden's transaction status or event as the source of truth for the payout outcome.
• [Mobile Money Payouts](https://docs.miden.co/collections-and-disbursements/disbursements/payout-methods/mobile-money-payouts.md): Mobile Money Payouts allow you to send funds directly to a recipient's mobile money account using their phone number and mobile money provider. Miden supports Mobile Money payouts for KES, UGX, and SLE . To complete a payout, select the applicable currency, provide the recipient's phone number and provider, enter the payout amount and narration, then initiate the transaction. Payouts can be initiated from the Miden Dashboard or programmatically through the Disbursement API . 1. Select the payout currency Select the currency corresponding to the recipient's market: KES — Kenya UGX — Uganda SLE — Sierra Leone The mobile money providers available for the payout depend on the selected currency and market. 2. Enter the recipient's phone number Provide the phone number associated with the recipient's mobile money account. Ensure that the phone number belongs to an account registered with the intended mobile money provider. 3. Select the mobile money provider Select the recipient's provider from the supported providers available for the selected market. The selected provider determines the mobile money network through which Miden routes the payout. 4. Enter the payout details Provide: Amount — The amount to send in the selected currency. Narration — A description or reference for the payout. Review the recipient, provider, and transaction details before proceeding. 5. Initiate the payout Once the required recipient and payout details have been provided, initiate the transaction. You can initiate a Mobile Money payout: From the Miden Dashboard . Programmatically through the applicable Disbursement API . For API-based payouts, use the request fields and validation requirements documented in API Reference → Disbursements . 6. Miden processes the payout Miden validates the request and routes the transaction through the selected mobile money provider to the recipient's mobile money account. 7. Confirm the outcome Use the transaction status or resulting webhook event provided by Miden to determine the final payout outcome. Do not treat successful submission of the payout request as confirmation that the recipient has received the funds. For information about payout statuses and outcomes, see Disbursement Lifecycle . Important Select the correct currency for the recipient's market. Ensure the phone number is associated with the selected mobile money provider. Confirm the payout amount and narration before submitting the transaction. Use Miden's transaction status or event as the source of truth for the payout outcome. Important Select the correct currency for the recipient's market. Ensure the phone number is associated with the selected mobile money provider. Confirm the payout amount and narration before submitting the transaction. Use Miden's transaction status or event as the source of truth for the payout outcome.
• [USD](https://docs.miden.co/business-accounts/usd.md): 1. Overview The USD Account system enables businesses and individuals to create, manage, and transact using USD accounts. The process involves application submission, account creation, beneficiary management, and various transaction capabilities. 2. Step-by-Step Process Step 1: Application Submission To open a USD account, the customer (business or individual) must submit an application. Endpoint for Businesses: This is used to create a business customer . Businesses must create a business profile through the system. Endpoint for Individuals: This is used to create an individual customer . Individuals must create an individual profile Retrieve Customer List: This is used to fetch a list of all customers Retrieve Specific Customer Details: This is used to fetch the details of a customer Step 2: Application Approval & Account Creation Once an application is approved, the customer can proceed to create a USD account. Create Account: A customer can create a USD account under their approved profile. Activate/Deactivate Account: Accounts can be activated or deactivated when needed. Retrieve All Accounts: A customer can retrieve a list of all their accounts. Retrieve Specific Account Details: A customer can view details of a specific account. Retrieve Account Statement: A customer can generate an account statement with filters like date range and account number. Step 3: Add Beneficiaries Before transacting, customers must add beneficiaries to their accounts. Add FIAT Beneficiary (NGN, USD, EUR): Customers can add FIAT beneficiaries (NGN, USD, EUR). Add Coin Beneficiary (Coming Soon): Step 4: Transactions Once a USD account is created and beneficiaries are added, customers can perform transactions. 4.1. Wallet Transfers (P2P Transactions) Customers can transfer funds between their wallets or to another user within the same system. 4.2. Coin Transfers (USDC, etc.) Customers can send USD and convert it to USDC via available payment rails. 4.3. NGN Transfers Customers can send USD and convert it to NGN, settling into a Nigerian bank account. 4.4. USD Transfers Customers can transfer USD directly to another USD account. 4.5. EUR Transfers Customers can transfer USD and convert it to EUR for international transactions. Step 5: Retrieve Transaction History Retrieve All Transactions: Customers can retrieve a list of all transactions for their accounts. Retrieve Specific Transaction Details: Detailed information about a specific transaction
  • [Business Industries](https://docs.miden.co/business-accounts/usd/business-industries.md): Summary: This folder contains a comprehensive list of the various business industries that our organization serves. This folder is designed to provide you with an easy reference point for understanding the sectors in which we operate, facilitating better alignment of services and solutions with industry-specific needs. Pass only the codes for desired business industries. Business Industries: Industries Codes Computer Systems Design and Related Services "5415" Management of Companies and Enterprises "5511" General Medical and Surgical Hospitals "6221" Offices of Physicians "6211" Elementary and Secondary Schools "6111" Depository Credit Intermediation "5221" Insurance Carriers "5241" Accounting, Tax Preparation, Bookkeeping, and Payroll Services "5412" Legal Services "5411" Advertising, Public Relations, and Related Services "5418" Real Estate Agents and Brokers "5312" Business Support Services "5614" Outpatient Care Centers "6214" Restaurants and Other Eating Places "7225" Individual and Family Services "6241" Home Health Care Services "6216" Architectural, Engineering, and Related Services "5413" Employment Services "5613" Office Administrative Services "5611" Colleges, Universities, and Professional Schools "6113" Nursing Care Facilities (Skilled Nursing Facilities) "6231" Software Publishers "5112" Data Processing, Hosting, and Related Services "5182" Travel Arrangement and Reservation Services "5615" Other Ambulatory Health Care Services "6219" Other Support Services "5619" Social Advocacy Organizations "8133" Other Financial Investment Activities "5239" Facilities Support Services "5612" Community Food and Housing, and Emergency and Other Relief Services "6242"
  • [Rejection Reasons](https://docs.miden.co/business-accounts/usd/rejection-reasons.md): Overview The Rejection Reasons folder provides a comprehensive list of common rejection reasons encountered during the identity verification process. These reasons are often related to inconsistencies, incomplete or unverifiable information, and issues with the documentation quality. Title Description miden_reason reason ID cannot be verified against databases Your information could not be verified Cannot validate user age Your information could not be verified Inconsistent or incomplete information. Inconsistent or incomplete information. Missing or incomplete barcode on the ID Cannot validate ID -- upload a clear photo of the full ID Inconsistent information in the barcode Your information could not be verified Submission is blurry Cannot validate ID - upload photo of ID is clear Inconsistent ID format Your information could not be verified Compromised ID detected Your information could not be verified ID from disallowed country Cannot accept provided ID Incorrect ID type selected Incorrect ID type selected. Same side submitted as both front and back Same side submitted as both front and back Electronic replica dete Your information could not be verified No government ID found in submission No government ID found in submission. ID is expired ID is expired Missing required ID details. Cannot validate ID -- upload a clear photo of the full ID. Inconsistent details in extraction. Your information could not be verified Likely fabrication detected. Your information could not be verified Glare detected in the submission. Cannot validate ID -- upload a clear photo of the full ID Identity cannot be verified Your information could not be verified Inconsistent details with previous submission. Your information could not be verified Inconsistent details between submissions. Your information could not be verified Machine readable zone not detected Cannot validate ID -- upload a clear photo of the full ID Inconsistent machine readable zone Cannot validate ID -- upload a clear photo of the full ID ID number format inconsistency Your information could not be verified Paper copy detected. Your information could not be verified PO box address detected. PO box address detected. Blurry face portrait. Cannot validate ID -- upload a clear photo of the full ID No face portrait found in the submission. Cannot validate ID -- upload a clear photo of the full ID Face portrait matches a public figure Your information could not be verified Not a U.S. REAL ID. Your information could not be verified ID details and face match previous submission. Your information could not be verified Different faces in ID and selfie. Your information could not be verified Tampering detected. Your information could not be verified Submission cannot be processed. Submission cannot be processed. Dates on the ID are invalid. Your information could not be verified Identity cannot be verified against databases Your information could not be verified Person is deceased. Your information could not be verified Document could not be verified Your information could not be verified Unsupported country Your region is not supported No government ID detected Cannot validate ID -- upload a clear photo of the full ID No database check was performed Your information could not be verified Prohibited state/province Your region is not supported Unsupported state/province Your information could not be verified Prohibited country Your information could not be verified Potential elder abuse Your information could not be verified Potential PEP Your information could not be verified Customer information could not be verified Your information could not be verified Missing or invalid proof of address Missing or invalid proof of address
  • [Most Recent Occupation (Individuals)](https://docs.miden.co/business-accounts/usd/most-recent-occupation-individuals.md): Description This folder contains a comprehensive list of occupation codes and their corresponding descriptions. These occupation codes represent the most recent professional roles held by individual customers. When submitting an application for an individual customer, pass only the codes for the individual's most recent occupation. Title Description Occupation Code Software Developer 151252 Registered Nurse 291141 Other Physician 2912XX Other Community and Social Service Specialist 21109X Computer Occupation, Other 151299 Customer Service Representative 434051 Other Financial Specialist 1320XX Project Management Specialist 131082 Web and Digital Interface Designer 151255 Media and Communication Worker, Other 273099 Medical and Health Services Manager 119111 Lawyer 231011 Legal Support Worker, Other 232099 Manager, Other 119199 Market Research Analyst and Marketing Specialist 131161 Marketing Manager 112021 Other Engineering Technologist and Technician 17302X Accountant and Auditor 132011 Computer Systems Analyst 151211 Unemployed, with no work experience in the last 5 years or earlier or never worked 999999
  • [High-Risk Activities](https://docs.miden.co/business-accounts/usd/high-risk-activities.md): Overview Money Services (i.e., check cashing, gift cards, ATMs, remittances) - "money_services" Lending / Banking - "lending_banking" Operate Foreign Exchange / Virtual Currencies Brokerage / OTC - "operate_foreign_exchange_virtual_currencies_brokerage_otc" Hold Client Funds (i.e., escrow) - "hold_client_funds" Investment Services - "investment_services"Safe Deposit Box Rentals - "safe_deposit_box_rentals" Marijuana or Related Services - "marijuana_or_related_services "Third-Party Payment Processing - "third_party_payment_processing "Adult Entertainment - "adult_entertainment "Weapons, Firearms, and Explosives - "weapons_firearms_and_explosives" Gambling - "gambling "None of the above - "none_of_the_above"
• [Get Access Token](https://docs.miden.co/get-access-token.md): Access tokens expire after 3600 seconds. (1 hour) Check the expires_in field in the response and re-request a token before expiry. Do not hardcode or store tokens long-term.
• [Dashboard](https://docs.miden.co/dashboard.md): This endpoint retrieves a summary of transaction, card, and wallet information for a user. Field Name Field Description Field Type Is Manadatory firstName First name of the customer String True lastName Last name of the customer String True phone Phone number of the customer String True address1 Primary address of the customer String True address2 Secondary address of the customer String False City City where the customer lives String True State State where the customer lives String True zipcode Zipcode of the customer's address String True country Country of the customer's address String True initialBalance Initial balance of the customer Integer True
• [Generate Webhook Signature Hash](https://docs.miden.co/get-started/generate-webhook-signature-hash.md): Overview: A Signature Hash is a cryptographic mechanism used to authenticate API requests and ensure that the payload has not been altered during transmission. It is generated using a secret key and a hashing algorithm, commonly HMAC-SHA256, to create a signature that proves the integrity and authenticity of the request. Usage : The Signature Hash is included in the headers of the API request (i.e., x-signature ) to allow your server to verify that the request comes from (Miden) and that the payload has not been tampered with. Your server computes its own hash using your webhook hash and compares it to the hash sent by Miden. If they match, the request is validated. How to Generate: To guarantee secure, cross-language verification of webhook messages, signatures must be computed using the exact value from the webhook request with formating Steps to Generate a Signature 1 Concatenate the eventId & eventTime properties Concatenate the eventId and eventTime proerties string cancatString = $"{eventId}&{eventTime}";. 2 Convert Raw JSON to Bytes Convert the cancatenated string to a sequence of bytes using UTF-8 encoding. 3 C ompute the Signature Use the HMAC-SHA256 algorithm (or the algorithm specified by your API) with your shared secret key and the raw JSON byte sequence. The output will be a sequence of bytes (the signature). 4 F ormat the Signature Convert the signature bytes to a lowercase hexadecimal string (remove any dashes or spaces between bytes). This final string is the signature hash . Steps to Verify a Signature (on Receiver Side) 1 Read the Raw HTTP Header Obtain the value for x-signature in the HTTP request header. 2 Compare Signatures Convert your computed signature to a lowercase hexadecimal string. Compare this value with the signature received in the request header. If they match exactly, the webhook is verified and untampered. Sample: JSON string webhookHash = "mySecret"; webhookPayload = { "cardId": "217172FB-119B-4DC7-833E-08DDBFAB49D0", "eventId": "26184906", "eventTime": "2025-07-24 13:32:55", "eventType": "purchase.card.withdrawal", "eventClass": "CardWithdrawal", "data": { "cardId": "217172FB-119B-4DC7-833E-08DDBFAB49D0", "amount": 1, "reason": "Test withdrawal - F97172FB-119B-4DC7-833E-08DDBFAB49D0 Withdrawal", "oldBalance": 610, "newBalance": 610, "transactionReference": "3e040fcbee624ae98e52", "cardTransactionId": 26184906 }, "processed": false, "uniqueKey": "6f10350b-1d00-4370-80f3-fc7b7a352e4d", "ignoreWebhook": false, "allowCardNegativeBalance": false, "messageTypeName": "WebhookMessage" } xSignature = 97b24d88261f899f4b8a63c0b1c6dc6f58cd64e36d01c6c6f0f86c0a5bc19a08 How to set your webhook hash Webhook hash is generated from your Miden Dashboard. Kindly for the steps below, to fetch your webhook hash: 1 Login Log in to your account using your email address, password and 2fa Token. 2 Go to ‘Settings’ Page From your Dashboard , click on your Settings button, on the top-right corner of your Dashboard screen. 3 Navigate to ‘Developer’ Page From your Settings page (Profile), click on your Developer module to set your webhook hash. This field allows for alphanumeric characters. After inputting these characters, click on the Update Application button to submit these entry. Copy the hash after submission, for your usage. Sample Code : This section provides code samples demonstrating signature generation for API requests in five different programming languages: C#, JavaScript (Node.js), JAVA , PHP, and Go . Each code snippet showcases the logic for constructing the base string and generating the signature based on your API's requirements. Snippets are below: C# using System; using System.Security.Cryptography; using System.Text; using System.Text.Json.Nodes; class Program { static void Main() { string webhookHash = "mySecret"; string webhookPayload = @" { ""cardId"": ""217172FB-119B-4DC7-833E-08DDBFAB49D0"", ""eventId"": ""26184906"", ""eventTime"": ""2025-07-24 13:32:55"", ""eventType"": ""purchase.card.withdrawal"", ""eventClass"": ""CardWithdrawal"", ""data"": { ""cardId"": ""217172FB-119B-4DC7-833E-08DDBFAB49D0"", ""amount"": 1, ""reason"": ""Test withdrawal - F97172FB-119B-4DC7-833E-08DDBFAB49D0 Withdrawal"", ""oldBalance"": 610, ""newBalance"": 610, ""transactionReference"": ""3e040fcbee624ae98e52"", ""cardTransactionId"": 26184906 }, ""processed"": false, ""uniqueKey"": ""6f10350b-1d00-4370-80f3-fc7b7a352e4d"", ""ignoreWebhook"": false, ""allowCardNegativeBalance"": false, ""messageTypeName"": ""WebhookMessage"" }"; // Parse the JSON var json = JsonNode.Parse(webhookPayload); string eventId = json?["eventId"]?.ToString() ?? ""; string eventTime = json?["eventTime"]?.ToString() ?? ""; string concatString = $"{eventId}&{eventTime}"; string signature = ComputeWebhookSignature(eventId, eventTime, webhookHash); Console.WriteLine($"Concat String: {concatString}"); Console.WriteLine($"Signature: {signature}"); } public static string ComputeWebhookSignature(string eventId, string eventTime, string sharedSecret) { string cancatString = $"{eventId}&{eventTime}"; var payloadBytes = Encoding.UTF8.GetBytes(cancatString); using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(sharedSecret)); var signature = hmac.ComputeHash(payloadBytes); return BitConverter.ToString(signature).Replace("-", "").ToLowerInvariant(); } } JSON const crypto = require('crypto'); // Your webhook payload as a JS object const webhookPayload = { cardId: "217172FB-119B-4DC7-833E-08DDBFAB49D0", eventId: "26184906", eventTime: "2025-07-24 13:32:55", eventType: "purchase.card.withdrawal", eventClass: "CardWithdrawal", data: { cardId: "217172FB-119B-4DC7-833E-08DDBFAB49D0", amount: 1, reason: "Test withdrawal - F97172FB-119B-4DC7-833E-08DDBFAB49D0 Withdrawal", oldBalance: 610, newBalance: 610, transactionReference: "3e040fcbee624ae98e52", cardTransactionId: 26184906 }, processed: false, uniqueKey: "6f10350b-1d00-4370-80f3-fc7b7a352e4d", ignoreWebhook: false, allowCardNegativeBalance: false, messageTypeName: "WebhookMessage" }; // Extract eventId and eventTime const eventId = webhookPayload.eventId; const eventTime = webhookPayload.eventTime; // Concatenate as per your hash algorithm const concatString = `${eventId}&${eventTime}`; console.log("Concat String:", concatString); const secret = "mySecret"; // Generate HMAC-SHA256 signature const hmac = crypto.createHmac('sha256', secret); hmac.update(concatString, 'utf8'); const signature = hmac.digest('hex'); console.log("Signature:", signature); Java import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; public class WebhookSignature { public static void main(String[] args) throws Exception { // Hardcoded values from your JSON String eventId = "26184906"; String eventTime = "2025-07-24 13:32:55"; String secret = "mySecret"; String concatString = eventId + "&" + eventTime; System.out.println("Concat String: " + concatString); String signature = computeWebhookSignature(concatString, secret); System.out.println("Signature: " + signature); } public static String computeWebhookSignature(String message, String secret) throws Exception { Mac sha256Hmac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); sha256Hmac.init(secretKey); byte[] hashBytes = sha256Hmac.doFinal(message.getBytes(StandardCharsets.UTF_8)); // Convert to lowercase hex string StringBuilder hexString = new StringBuilder(2 * hashBytes.length); for (byte b : hashBytes) { String hex = Integer.toHexString(0xff & b); if (hex.length() == 1) hexString.append('0'); hexString.append(hex); } return hexString.toString(); } } PHP // Your values extracted from the JSON payload $eventId = "26184906"; $eventTime = "2025-07-24 13:32:55"; $secret = "mySecret"; // Concatenate eventId and eventTime with & $concatString = $eventId . "&" . $eventTime; echo "Concat String: $concatString\n"; // Generate HMAC-SHA256 $signature = hash_hmac('sha256', $concatString, $secret); echo "Signature: $signature\n"; ?> Go package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "fmt" ) func main() { eventId := "26184906" eventTime := "2025-07-24 13:32:55" secret := "mySecret" concatString := eventId + "&" + eventTime fmt.Println("Concat String:", concatString) signature := computeWebhookSignature(concatString, secret) fmt.Println("Signature:", signature) } func computeWebhookSignature(message, secret string) string { h := hmac.New(sha256.New, []byte(secret))
• [Resend Transaction Webhook](https://docs.miden.co/get-started/resend-transaction-webhook.md): Overview This endpoint allows you to resend previously generated card transaction webhook events by supplying one or more transaction IDs. It is designed for recovery and replay scenarios where webhook notifications may have failed, timed out, or were not successfully processed by the receiving system. Usage Use this endpoint to: Re-trigger missed card transaction webhook events. Recover failed webhook deliveries. Synchronize card transaction state across systems. Replay historical card transaction notifications. Reconcile missing transaction records in downstream services. Test webhook processing workflows using existing transaction IDs. Expected Behaviour When this endpoint is called: The system validates all supplied transaction IDs. Previously generated card transaction webhook events linked to those transactions are re-triggered. Original webhook payloads are resent to the subscribed webhook URL(s). Existing event structures and event types remain unchanged. Failed or missed webhook deliveries can be recovered without creating duplicate transactions. Typical Use Cases Scenario Purpose Webhook timeout Replay webhook after receiver timeout Server downtime Recover events missed during an outage Failed processing Retry events after fixing application errors Data reconciliation Restore missing card transaction records Testing Replay production-like webhook payloads Notes This endpoint only resends existing card transaction webhook events. It does not create new transactions or generate new webhook events. Multiple transaction IDs can be supplied in a single request. Ensure idempotent webhook processing on your server to avoid duplicate processing. Invalid or non-existent transaction IDs may be ignored or return errors depending on implementation. Original webhook payloads and event types remain unchanged during replay.
• [Card KYC Webhook](https://docs.miden.co/card-webhooks/card-kyc-webhook.md): Webhooks Card KYC webhooks notify your application whenever the status of a verification changes. Supported webhook events include: kyc.initiated kyc.pending kyc.approved kyc.rejected Refer to the Card KYC Webhooks section for webhook payloads and event descriptions. Notes All Card KYC endpoints require authentication. Use a unique Reference header for every request. Store the returned kycToken , as it is required to retrieve the verification status. Verification may be synchronous or asynchronous depending on the selected verification method. Sensitive customer information, including identity numbers and document images, should be handled securely and must not be exposed in logs or client-side applications. A successful KYC submission does not necessarily indicate that the customer has been verified. Always check the final verification status or consume webhook notifications before proceeding with card issuance or other restricted operations.
  • [Card KYC](https://docs.miden.co/card-webhooks/card-kyc-webhook/card-kyc.md): Overview The KYC Approved webhook is triggered whenever an individual or business customer successfully completes the Card KYC verification process. This webhook confirms that the customer's identity has been verified and that the customer is eligible to proceed with card-related operations, subject to your organization's onboarding policies. Supported events include: kyc.initiated kyc.pending kyc.approved kyc.rejected Each webhook contains information about the customer, the verification request, and the latest KYC status, allowing your application to keep customer records synchronized without polling the KYC Status endpoint. Usage Use this webhook to: Use this webhook to: Track the progress of KYC verification. Update customer KYC status automatically. Trigger onboarding workflows. Enable or restrict card operations based on verification outcome. Notify customers when their verification status changes. Event Class CardKyc Event Types Event Description kyc.initiated A KYC request has been accepted for processing. kyc.pending The verification is currently being processed. kyc.approved The customer has successfully passed verification. kyc.rejected The customer failed verification. Expected Behaviour When this webhook is received, your system should: Verify the webhook signature. Match the customerId or kycToken with your customer record. Update the customer's KYC status to Approved . Store the verification timestamp. Trigger any post-verification onboarding actions. Notes Every webhook event contains a unique eventId . A KYC approval is considered final unless a subsequent review is initiated. Store the kycToken for reconciliation and audit purposes. Always validate the webhook signature before processing the payload. Use eventId to prevent duplicate processing. Do not rely on webhook delivery order; always update records based on the latest status received. Store the kycToken and customerId for reconciliation and audit purposes. The reason field is populated only when the verification is rejected. If webhook delivery fails, retrieve the latest verification status using the Get Card KYC Status endpoint.
• [Blocks and Terminations](https://docs.miden.co/card-webhooks/blocks-and-terminations.md): Description: This folder contains endpoints for managing events related to the blocking and termination of cards, crucial for preventing fraud and ensuring regulatory compliance. It handles scenarios such as general blocked cards, suspected fraud, and termination due to inactivity, providing detailed information for appropriate actions. Usage: Endpoints in this folder send real-time notifications about card blocking and termination, allowing recipient systems to update records, notify users, and take necessary actions promptly, thus enhancing security and compliance.
  • [Card Termination](https://docs.miden.co/card-webhooks/blocks-and-terminations/card-termination.md): Overview The Card Termination webhook is triggered whenever a card is intentionally terminated through the Card Termination endpoint. This includes terminations initiated either by the merchant through the API or dashboard, or by Miden as part of an administrative or operational action. The webhook provides information such as the card ID, termination reason, balance before and after termination, and transaction reference, allowing downstream systems to immediately reflect the card's terminated status. Usage Use this webhook to: Update the card status to Terminated in your systems. Prevent any further transactions on the card. Notify cardholders or administrators that the card has been deliberately terminated. Reconcile the final card balance and any post-termination activities. Event Type purchase.card.terminate Event Class CardTermination Expected Behaviour When this webhook is received, your system should: Verify that the event type is purchase.card.terminate . Match the cardId to the card in your system. Record the termination event and reason. Reconcile the balance movement using: amount oldBalance newBalance transactionReference Notes Each webhook event is uniquely identified by eventId . eventTime can be used for event ordering and audit history. The transactionReference can be stored for reconciliation and support purposes. The newBalance will typically reflect the remaining balance after termination processing, always 0.
  • [Terminated Card: Insufficient Funds](https://docs.miden.co/card-webhooks/blocks-and-terminations/terminated-card-insufficient-funds.md): Overview The Terminated Card: Insufficient Funds webhook is triggered automatically when a card is terminated because a purchase authorization is declined due to insufficient funds and the card reaches the configured insufficient-funds termination threshold. Unlike the standard Card Termination webhook, this event is not triggered by an explicit termination request. Instead, it indicates that the card was automatically terminated by the platform following repeated or threshold-based insufficient-funds authorization failures. Usage Use this webhook to: Update the card status to Terminated in your systems. Distinguish automatic, insufficient-funds terminations from manually initiated terminations. Prevent further transaction attempts on the terminated card. Notify cardholders or administrators that the card was terminated due to insufficient funds. Record and reconcile the final balance movement associated with the automatic termination. Event Type purchase.card.auth.declined.terminate Event Class CardTermination Expected Behaviour Upon receiving this webhook, your system should: Confirm the eventType is purchase.card.auth.declined.terminate . Identify the affected card using cardId . Record the failed authorization attempt ( amount , merchantIdentifier ). Log the termination reason ( Insufficient Funds ). Handle balance reconciliation: If balanceCreditedIntoWallet = true , reconcile using creditTransactionId . Notes This webhook represents a card termination event . eventClass is CardTermination , — this is expected behavior. merchantIdentifier may be null depending on the transaction context. Always implement idempotency using eventId
  • [Blocked Card](https://docs.miden.co/card-webhooks/blocks-and-terminations/blocked-card.md): Overview This webhook endpoint is triggered when a card is blocked for general reasons, not limited to suspected fraud. It provides detailed information about the blocking event and the specific card involved. Usage: Used to notify systems and stakeholders about a card being blocked, allowing them to update records, inform the cardholder, and take necessary administrative or security measures. Event Type purchase.card.auth.declined.blocked Event Class CardBlock Expected Behaviour When this webhook is received, your system should: Validate that the eventType is purchase.card.auth.declined.blocked . Identify the affected card using CardId . Mark the card as blocked or frozen in your system. Record the reason for the block using the Reason field. Log the attempted transaction amount using Amount . Use EventId to prevent duplicate processing. Reconcile any wallet credit if BalanceCreditedIntoWallet is true . Notes This is a block event , not a termination event. Action is Freeze , which means the card is restricted from use until further action is taken. Amount represents the attempted transaction amount and is not deducted from the card. BalanceBeforeTermination is also used in block events, even though the field name refers to termination. MerchantIdentifier may be null if merchant details are unavailable. For safe processing, implement idempotency using EventId
  • [Blocked Card: Suspected Fraud](https://docs.miden.co/card-webhooks/blocks-and-terminations/blocked-card-suspected-fraud.md): Overview This webhook endpoint is triggered when a card is blocked due to suspected fraudulent activity. It provides detailed information about the suspicious activity and the specific card involved. Usage: Used to notify systems and stakeholders about the blocking of a card due to suspected fraud, enabling them to take immediate action to prevent further unauthorized transactions, update records, inform the cardholder, and initiate an investigation. Event Type purchase.card.auth.declined.blocked Event Class CardBlock Expected Behaviour When this webhook is received: Validate eventType = purchase.card.auth.declined.blocked . Identify the card using cardId . Mark the card as blocked/frozen in your system. Log the attempted transaction ( amount , merchantIdentifier ). Record the reason ( Suspected Fraud ). Prevent further transactions until the card is reviewed or reactivated. Ensure idempotency using eventId . Notes This is a block (freeze) event, not a termination . action = "Freeze" is key — the card can potentially be reactivated later. No balance movement typically occurs ( balanceCreditedIntoWallet = false ). amount represents the attempted transaction , not a deduction.
  • [Regularize Terminated Card](https://docs.miden.co/card-webhooks/blocks-and-terminations/regularize-terminated-card.md): Overview This webhook is triggered when a terminated card is successfully regularized . It provides details about the regularization process, including the amount applied to clear the negative balance, the card’s balance before and after regularization, and the associated transaction reference.
• [Pre-Authorized Approval](https://docs.miden.co/card-webhooks/authorization-and-settlement/pre-authorized-approval.md): Overview: This webhook is triggered when a card transaction is pre-authorized during a purchase transaction. Pre-authorizations are a rare type of authorization typically used in scenarios where the final transaction amount is not yet known —for example, at hotels, gas stations, or ride-hailing services. Note: The final settlement amount is often higher than the pre-authorized amount. You should design your systems to account for a follow-up settlement webhook ( purchase.card.settlement_ ) that finalizes the actual amount. This transcation type (pre-authorization approval) is more common with Mastercard.
• [Approved Authorization](https://docs.miden.co/card-webhooks/authorization-and-settlement/approved-authorization.md): Overview: This webhook endpoint notifies clients when a card authorization has been successfully approved during a purchase transaction. It provides detailed information about the transaction, including transaction ID, amount, currency, card network, merchant details, and authorization status. Usage: The Approved Authorization webhook is used to inform client systems about successful card authorization events. Clients can utilize this information to update transaction records, notify users about successful transactions, and maintain accurate financial records. Event Type purchase.card.auth.approved Event Class Settlement Expected Behaviour When this webhook is received, your system should: Validate that eventType is purchase.card.auth.approved . Identify the affected card using cardId . Record the approved transaction using cardTransactionId . Store transaction details such as amount, currency, merchant, and authorization code. Update the card’s available balance using availableBalance . Notify the user of the successful transaction, if applicable. Use eventId to prevent duplicate processing. Notes This webhook confirms that the transaction authorization was successful. availableBalance represents the remaining card balance after the authorization. authorizationAmount may be sent as a string, so use amount for numerical calculations where applicable. Store authCode , cardTransactionId , and orderNumber for reconciliation and support purposes.
• [Declined Authorization](https://docs.miden.co/card-webhooks/authorization-and-settlement/declined-authorization.md): Overview: This webhook endpoint notifies clients when a card authorization has been declined. It provides detailed information about the declined transaction, including transaction ID, amount, currency, card network, merchant details, and reason for decline. Usage: Used to inform client systems about declined card authorization events. Clients can update transaction records, notify users about declined transactions, and manage authorization failures effectively.
• [Settled Authorization](https://docs.miden.co/card-webhooks/authorization-and-settlement/settled-authorization.md): Overview This webhook endpoint is triggered when a card authorization has been successfully settled . It provides detailed information about the completed transaction, including the settled amount, merchant details, and updated balance.
• [Expired Authorization](https://docs.miden.co/card-webhooks/authorization-and-settlement/expired-authorization.md): Overview This webhook endpoint is triggered when a card authorization expires after a defined period (typically 7 days) without being settled . It provides details about the expired authorization transaction and associated merchant information.
• [Refund Authorization](https://docs.miden.co/card-webhooks/refunds-and-reversals/refund-authorization.md): Overview This webhook endpoint is triggered when a refund authorization is successfully approved for a card transaction . It provides detailed information about the refund, including the refunded amount, merchant details, and updated balance. Usage Used to notify systems when a refund has been authorized, enabling transaction updates, balance adjustments, and accurate reconciliation. Event Type purchase.card.return.auth.approved Event Class Settlement Expected Behaviour When this webhook is received: Validate eventType = purchase.card.return.auth.approved Identify the card using cardId Retrieve refund details from the data object Record the refund transaction using cardTransactionId Update transaction status to Refund Authorized Increase/update balance using availableBalance Log merchant details ( merchantName , merchantIdentifier ) Record authorization details ( authCode , authorizationAmount ) Store orderNumber for reconciliation Ensure idempotency using eventId Notes This event represents a refund authorization , not final refund settlement Funds may not yet be fully returned — this is an approval stage amount represents the refund value being authorized availableBalance may reflect updated balance depending on system behavior This should be followed by a refund settlement event (if applicable) Always ensure idempotent handling using eventId
• [Refund Settlement](https://docs.miden.co/card-webhooks/refunds-and-reversals/refund-settlement.md): Overview This webhook endpoint is triggered when a refund transaction has been successfully settled . It provides detailed information about the settled refund, including transaction details, merchant information, and updated balance. Usage Used to notify systems when a refund has been fully settled, enabling accurate reconciliation, transaction finalization, and financial reporting. Event Type purchase.card.return.auth.settled Event Class Settlement Expected Behaviour When this webhook is received: Validate eventType = purchase.card.return.auth.settled Identify the card using cardId Retrieve settlement details from the data object Record the refund settlement using cardTransactionId Update transaction status to Refund Settled Confirm refund completion (final state of refund lifecycle) Update balance using availableBalance Log merchant details ( merchantName , merchantIdentifier ) Store orderNumber for reconciliation Ensure idempotency using eventId Notes This event represents the final stage of a refund lifecycle Unlike refund authorization, this confirms actual settlement of funds amount represents the final refunded amount Systems should treat this as a completed refund transaction Always ensure idempotent processing using eventId This event should follow a Refund Authorization webhook
• [Refund Settlement: Terminated Cards](https://docs.miden.co/card-webhooks/refunds-and-reversals/refund-settlement-terminated-cards.md): Overview This webhook endpoint is triggered when a refund is successfully settled for a terminated card . It provides detailed information about the refund, including the refunded amount, transaction reference, and whether the funds were credited back to the customer’s wallet . (your wallet) Usage Used to notify systems about refunds processed after a card has been terminated, enabling accurate reconciliation, wallet balance updates, and transaction tracking. Event Type purchase.card.terminated.refund.settled Event Class RefundSettlement Expected Behaviour When this webhook is received: Validate eventType = purchase.card.terminated.refund.settled Identify the card using CardId Confirm the card is already terminated Extract refund details from the Data object Record the refund using CardTransactionId Verify refund completion using RefundProcessed = true Credit funds to wallet if BalanceCreditedIntoWallet = true Update internal ledger and wallet balance Store CreditTransactionId for reconciliation Log narration for audit trail Ensure idempotency using EventId Notes This event applies only to terminated cards Refunds are not returned to the card , but to the customer’s wallet/position (your wallet) BalanceCreditedIntoWallet = true is critical — confirms funds movement This is a post-termination financial adjustment event Always ensure idempotent handling using EventId This event may occur days after card termination depending on merchant processing timelines
• [Reversed Authorization](https://docs.miden.co/card-webhooks/refunds-and-reversals/reversed-authorization.md): Overview This webhook endpoint is triggered when a previously authorized transaction is reversed and settled . It provides detailed information about the reversed transaction, including amount, merchant details, and updated balance.
• [Card Issuance](https://docs.miden.co/card-webhooks/transactions-and-payments/card-issuance.md): Overview This webhook endpoint is triggered when a new card is successfully issued . It provides detailed information about the card, including its status, cardholder details, limits, and activation state. Usage Used to notify systems when a new card has been issued, enabling updates to internal records, user notifications, and synchronization of card data across systems. Event Type purchase.card.issued Event Class Purchase Expected Behaviour When this webhook is received: Validate eventType = purchase.card.issued Identify the card using cardId Create/store the new card record in your system Update card status using cardStatus Store cardholder details ( nameLine1 , nameLine2 ) Save card metadata ( lastFour , expirationDate , actualExpirationDate ) Initialize card limits ( usageLimit , amountLimit , limitWindow ) Set available balance using availableBalance Apply merchant controls ( midWhitelist , midBlacklist ) Mark card as active if activated = true Ensure idempotency using eventId Note This event represents card creation and activation readiness activated = true means the card is immediately usable usageLimit = -1 indicates no restriction on usage count amountLimit typically equals the funded card balance Merchant controls ( midWhitelist , midBlacklist ) may be empty or configured Always ensure idempotent processing using eventId This is typically the first lifecycle event for a card You might not receive this webhook because the result of creating a card is instant. It either fails or is created.
• [Lite Card Swipe Count Exceeded](https://docs.miden.co/card-webhooks/transactions-and-payments/lite-card-swipe-count-exceeded.md): Overview This webhook is triggered when a Lite (non-reloadable) card exceeds its allowed swipe/transaction count . The transaction is declined, and the event provides details about the attempted transaction and the reason for the decline.
• [Cross Border Charge](https://docs.miden.co/card-webhooks/transactions-and-payments/cross-border-charge.md): Overview This webhook is triggered when a cross-border charge is applied to a card transaction . It provides details about the transaction, including merchant information, charge amount, and transaction status (Approved or Pending).
• [Cross Border Charge Reversal](https://docs.miden.co/card-webhooks/transactions-and-payments/cross-border-charge-reversal.md): Overview This webhook is triggered when a previously applied cross-border charge is reversed . It provides details about the original transaction and the reversal, ensuring systems can correctly update balances and transaction records. Usage Used to notify systems when a cross-border fee has been reversed. This enables proper reconciliation, balance adjustments, and accurate financial reporting. Event Type purchase.card.cross-border.reversal ⚠️ Another possible event: purchase.card.cross-border.reversal.pending (Pending occurs when the reversal has been calculated but cannot yet be applied immediately. It may be processed later.) Event Class CrossBorder Expected Behaviour When this webhook is received: Validate eventType (reversal or reversal.pending) Identify the card using cardId Locate the original cross-border charge using cardTransactionId If Approved (reversal) : Reverse the cross-border fee Update wallet/card balance If Pending : Record reversal as pending Apply adjustment when processed Mark the charge as reversed in your system Log the reversal event for audit purposes Notify the user (optional) Ensure idempotency using eventId Notes This is a reversal event , not a new charge It cancels or refunds a previously applied cross-border fee transactionAmount represents the fee being reversed Always link this event to the original charge using cardTransactionId Ensure balances are correctly adjusted after reversal Use eventId to prevent duplicate processing
• [Card Account Verification](https://docs.miden.co/card-webhooks/transactions-and-payments/card-account-verification.md): Overview This webhook is triggered when a card account verification request is completed successfully . It typically occurs during card validation (e.g., $0/$1 authorization checks) to confirm that the card is active and usable.
• [Contactless Payment Charge](https://docs.miden.co/card-webhooks/transactions-and-payments/contactless-payment-charge.md): Overview This webhook is triggered when a contactless payment charge is applied to a card transaction . It provides details about the transaction, including merchant information, charge amount, and transaction status. Usage Used to notify systems about contactless payment charges. This enables real-time updates of transaction records, balance adjustments, and accurate tracking of contactless transaction fees. Event Type purchase.card.contactless-payment.settled ⚠️ Another possible event: purchase.card.contactless-payment.pending (Pending occurs when the charge has been calculated but cannot be applied immediately due to insufficient balance. It may be recovered later.) Event Class ContactlessPayment Expected Behaviour When this webhook is received: Validate eventType (settled or pending) Identify the card using cardId Read transactionStatus : Approved → charge successfully applied Pending → insufficient balance, recovery may occur later Record the contactless charge against the transaction Update wallet/card balance if applicable Store merchant and transaction metadata Notify user (optional) about contactless charge Ensure idempotency using eventId Notes This is a charge event , not the original contactless tap transaction transactionAmount represents the contactless fee , not the purchase amount Pending charges may be recovered later (e.g., month-end settlement) Always handle both: settled → immediate charge pending → delayed recovery Ensure idempotent processing using eventId
• [Activation OTP - Contactless Cards](https://docs.miden.co/card-webhooks/transactions-and-payments/activation-otp-contactless-cards.md): Overview This webhook is triggered when an OTP is generated or re-generated for activating a contactless card. It provides the activation code along with customer details required to complete the card activation process securely. Usage Used to notify systems when a contactless card activation OTP is generated or resent. This enables: Sending OTP to the customer (email/SMS) Initiating or retrying card activation workflows Verifying customer identity before activation Ensuring secure activation of contactless cards Event Type purchase.card.contactless.activation purchase.card.contactless.activation.resend Event Class ContactlessCardActivation Expected Behaviour When this webhook is received: Validate event type: purchase.card.contactless.activation purchase.card.contactless.activation.resend Identify the customer using customerId Extract the activationCode (OTP) If eventType = purchase.card.contactless.activation : Send OTP to the customer Start activation flow If eventType = purchase.card.contactless.activation.resend : Invalidate previous OTP Generate/send new OTP Restart activation flow Allow user to submit OTP for verification Activate card only after successful OTP validation Enforce: OTP expiry Retry limits Rate limiting Ensure idempotency using eventId Notes This webhook does NOT mean the card is activated It only represents OTP generation for activation Card activation must happen after OTP verification Latest OTP is always the valid one Previous OTPs should be invalidated on resend Do NOT log OTP in plaintext (security risk) Implement: Expiry (e.g. 5 mins) Retry limits Rate limiting
• [Card Withdrawal](https://docs.miden.co/card-webhooks/transactions-and-payments/card-withdrawal.md): Overview This webhook is triggered when a withdrawal is made from a card balance . It provides details about the deducted amount, previous and updated balances, and transaction reference.
• [Card Topup](https://docs.miden.co/card-webhooks/transactions-and-payments/card-topup.md): Overview This webhook is triggered when a card is successfully funded (topped up) . It provides details about the credited amount, previous balance, updated balance, and transaction reference. Usage Used to notify systems about card top-ups. This enables: Updating card balance in real time Recording credit transactions Maintaining accurate financial records Triggering user notifications for successful funding Event Type purchase.card.topup Event Class CardTopUp Expected Behaviour When this webhook is received: Validate eventType = purchase.card.topup Identify the card using cardId Extract transaction details from data Credit the amount to the card balance Verify: oldBalance → previous state newBalance → updated state after top-up Record the transaction using transactionReference Log the reason for audit and reconciliation Update internal systems (wallet, ledger, reporting) Notify customer of successful top-up (optional) Ensure idempotency using eventId Notes This is a credit event (balance increases) newBalance should always equal oldBalance + amount Ensure reconciliation with internal ledger systems Use transactionReference for tracking and audits Handle duplicate webhook events using eventId No reversal implied — separate webhook handles reversals/refunds if applicable
• [Purchase Card Expiration](https://docs.miden.co/card-webhooks/expirations/purchase-card-expiration.md): Overview This webhook is triggered when a card is approaching its expiration date . It provides the expiration date and the number of days remaining before expiry. Usage Used to notify systems about upcoming card expirations. This enables: Proactively notifying customers about card expiry Initiating card renewal or reissuance processes Preventing service disruption due to expired cards Updating internal systems with expiration timelines Event Type purchase.card.expiration Event Class CardExpiration Expected Behaviour When this webhook is received: Validate eventType = purchase.card.expiration Identify the card using cardId Extract expiration details from data Capture: ExpirationDate ExpirationInDays Trigger customer notification (email/SMS/in-app) Initiate card renewal/reissuance workflow (if applicable) Flag the card as expiring soon in your system Prevent disruption by ensuring replacement card is issued before expiry Ensure idempotency using eventId Notes This is a notification event , not a transaction No balance impact occurs Triggered before actual expiration (e.g., 30 days prior) Use this event to ensure seamless card replacement Avoid service disruption by issuing replacement cards early ExpirationInDays may be string-based — parse carefully Handle duplicate events using eventId
• [Terminated Expired Card](https://docs.miden.co/card-webhooks/expirations/terminated-expired-card.md): Overview This webhook is triggered when an expired card is terminated and any remaining balance is refunded . It provides details about the refunded amount, previous balance, updated balance, and transaction reference. Usage Used to notify systems when an expired card is fully closed and funds are settled. This enables: Processing refund of remaining balance Updating card status to terminated Reconciling wallet/ledger balances Maintaining accurate financial records Event Type purchase.card.expiration.terminate Event Class CardExpiration Expected Behaviour When this webhook is received: Validate eventType = purchase.card.expiration.terminate Identify the card using cardId Mark the card as terminated in your system Extract transaction details from data If amount > 0 : Process refund of remaining balance Credit funds to wallet/account Verify: oldBalance → previous balance newBalance → expected to be 0 after termination Record the transaction using transactionReference Log the reason for audit and reconciliation Ensure no further transactions are allowed on the card Ensure idempotency using eventId Notes This is a terminal event — card lifecycle ends here Card must be marked inactive/closed permanently Remaining balance (if any) is refunded newBalance should always be 0 after termination No further transactions should be allowed Handle duplicate events using eventId expirationDate and expirationInDays may be null because card is already expired
• [Webhook Subscripion](https://docs.miden.co/card-webhooks/events-and-subscriptions/webhook-subscripion.md): Overview This endpoint is used to configure or update webhook URLs where your system will receive real-time event notifications from Miden. It allows you to define endpoints for both card events and collection events , along with a validation hash for security. Usage Use this endpoint to: Register webhook URLs for receiving events Update existing webhook configurations Enable real-time synchronization with Miden systems Secure webhook communication using a validation hash Expected Behaviour When this request is sent: System validates all provided URLs Ensures webhookHash is alphanumeric only Updates webhook configuration for the account Future events will be delivered to the specified URLs Existing webhook URLs (if any) are overwritten Notes Both URLs must be publicly accessible HTTPS endpoints webhookHash is used later to validate incoming webhook payloads Keep the hash secure and private Invalid URLs or malformed hash will result in request failure This endpoint is idempotent — repeated calls overwrite previous config
• [Get Settlement Event Details](https://docs.miden.co/card-webhooks/events-and-subscriptions/get-settlement-event-details.md): This endpoint returns a list of all settlement events
• [KYC/Application Webhook](https://docs.miden.co/business-accounts-webhooks/usd/kyc-application-webhook.md): Overview This webhook is triggered whenever there is a change in the KYC (Know Your Customer) or onboarding application status of a customer. It provides real-time updates about the customer’s verification lifecycle, including stages such as pending, under review, approved, rejected, or requiring additional input. Usage Used to: Track customer onboarding progress Monitor KYC verification lifecycle Trigger internal workflows (e.g., enable account, request documents) Notify stakeholders or users about status changes Maintain compliance and audit records Event Type accounts.customer.kyc.awaiting_questionnaire ⚠️ Other Possible Event Types accounts.customer.kyc.not_started accounts.customer.kyc.pending accounts.customer.kyc.incomplete accounts.customer.kyc.awaiting_questionnaire accounts.customer.kyc.under_review accounts.customer.kyc.approved accounts.customer.kyc.rejected Event Class AccountsCustomer Expected Behaviour When this webhook is received: Validate eventType to determine the exact KYC stage Identify the customer using customerId Update KYC status in your system Trigger actions based on status: not_started → just submitted; inquiry has been created awaiting_questionnaire → customer's details is starting to be evaluated pending / under_review → wait for processing; custome rhas been flagged for compliance review. approved → activate account / enable features rejected → restrict account and notify user Store event for audit and compliance tracking Ensure idempotency using eventId Notes KYC is a multi-stage lifecycle , not a single event Same webhook structure is used for all KYC states kycStatus and eventType will always align approved status typically indicates onboarding completion rejected or incomplete may require manual intervention Events can arrive multiple times — always ensure idempotency
• [Inflow Webhook](https://docs.miden.co/business-accounts-webhooks/usd/inflow-webhook.md): Overview This webhook is triggered when funds are received into a USD account . It provides detailed information about incoming transactions, including deposit details, processing stages, fees, conversion values, and source information.
• [Account Drain Webhook](https://docs.miden.co/business-accounts-webhooks/usd/account-drain-webhook.md): Overview This webhook is triggered when funds are being moved out of a USD account (account drain). It provides real-time updates on the lifecycle of the drain process, including submission, processing, and completion stages.
• [Transfer Webhook](https://docs.miden.co/business-accounts-webhooks/usd/transfer-webhook.md): Overview This webhook is triggered when a fund transfer is initiated, processed, or completed from a USD account. It provides detailed information about the transfer, including amount, fees, destination, processing state, and transfer type (bank, internal, or network).
• [NGN Collections](https://docs.miden.co/business-accounts-webhooks/ngn/ngn-collections.md): Overview This webhook is triggered whenever a collection is successfully received through a NGN Virtual Account . It provides detailed transaction information including the sender’s account details, transaction references, settlement amount, narration, and processing status. Usage Used to notify merchant systems in real time when funds are received into a NGN virtual account. This allows businesses to automatically reconcile payments, update customer balances, confirm deposits, and trigger downstream workflows. Event Type collection.virtual-accounts Event Class Collections Expected Behaviour When this webhook is received: Validate eventType Identify the receiving virtual account using virtualAccountNumber Confirm transaction success using status Match payment using merchantReference or transactionReference Record payer information from sourceAccountName and sourceAccountNumber Reconcile settlement using SettledAmount Update merchant/customer balances Trigger payment confirmation workflows Store narration and references for audit purposes Ensure idempotent processing using eventId Notes This webhook applies specifically to NGN virtual account collections transactionAmount represents the full customer payment SettledAmount represents the amount credited after deductions merchantReference should be used for merchant-side reconciliation transactionReference is the platform-generated tracking reference sourceAccountNumber and sourceAccountName identify the payer Always process duplicate webhook retries safely using eventId channel remains VirtualAccount for virtual account collections
• [Re-process Collection Webhook](https://docs.miden.co/business-accounts-webhooks/ngn/re-process-collection-webhook.md): **Description:**This endpoint allows you to create a new static virtual account for a user.
• [Invoice Webhook](https://docs.miden.co/accrual-webhooks/invoice-webhook.md): Overview This webhook is triggered when an invoice event occurs, such as when an invoice is created or paid. It provides invoice payment details including invoice number, amount, customer information, channel, status, and currency. Usage Used to notify systems about invoice lifecycle updates. This enables merchants to track invoice creation, confirm invoice payments, update customer records, and reconcile paid invoice transactions. Event Type invoice.paid ⚠️ Other Possible Event Types invoice.created invoice.paid Event Class Invoices Expected Behaviour When this webhook is received: Validate eventType Identify the invoice using invoiceNumber Update invoice status using status If eventType = invoice.created , record the invoice as created If eventType = invoice.paid , mark invoice as paid Confirm amountPaid and balanceAmount Record payment channel and currency Update customer payment history Reconcile payment using invoice amount and paid amount Ensure idempotency using eventId Notes invoice.paid confirms that payment has been completed balanceAmount = 0.00 means the invoice has been fully paid channel shows how the customer paid the invoice Always use eventId to avoid duplicate processing Use invoiceNumber as the main invoice reference for lookup and reconciliation
• [Card Collection Webhook](https://docs.miden.co/accrual-webhooks/card-collection-webhook.md): Overview This webhook is triggered whenever a payment collection is successfully completed using a card payment method within the Accrual payment infrastructure. It provides transaction details including the charged amount, settled amount, transaction references, payment channel, and collection status. Usage The Card Collections webhook is used to notify merchant systems in real time whenever a customer successfully completes a card payment. This enables businesses to automatically reconcile payments, update invoice statuses, confirm successful collections, trigger order fulfillment, and maintain synchronized financial records. Expected Behaviour When this webhook is received: Validate the webhook signature/hash Confirm the eventType is collection.cards Verify transaction status using status Match the transaction using merchantReference or transactionReference Confirm settlement values using transactionAmount and settledAmount Update invoice or payment records Mark orders or subscriptions as paid where applicable Store transaction metadata for reconciliation and auditing Ensure idempotent processing using eventId Notes This webhook applies specifically to card-based collections transactionAmount represents the full amount paid by the customer settledAmount represents the net settled value after deductions or fees merchantReference should be used for merchant-side reconciliation transactionReference is generated by the platform for transaction tracking channel will always indicate the payment source ( Cards ) Always implement idempotent handling to safely process webhook retries Webhook events may be resent if delivery retries occur
• [Virtual Account Collection (NGN) Webhook](https://docs.miden.co/accrual-webhooks/virtual-account-collection-ngn-webhook.md): Overview This webhook is triggered whenever a collection payment is successfully received through a virtual account within the Accrual payment infrastructure. It provides detailed information about the collection transaction, including the payer’s account details, transaction references, settlement values, and payment status. Usage The Virtual Account Collections webhook enables merchant systems to receive real-time notifications whenever a customer completes a payment using a dedicated virtual account. This allows businesses to automatically reconcile incoming payments, update invoices, confirm deposits, trigger fulfillment processes, and maintain synchronized financial records. Event Type collection.virtual-accounts Event Class Collections Expected Behaviour When this webhook is received: Validate the webhook signature/hash Confirm the eventType is collection.virtual-accounts Verify the transaction status using the status field Match transactions using merchantReference or transactionReference Confirm payment destination using virtualAccountNumber Store payer details such as sourceAccountName and sourceBankName Update invoices, balances, or customer records Trigger fulfillment or service activation if applicable Reconcile settlement values using transactionAmount and settledAmount Ensure idempotent processing using eventId Notes This webhook applies specifically to virtual account collections virtualAccountNumber identifies the receiving account assigned to the customer or merchant transactionAmount represents the total amount paid by the customer settledAmount represents the net amount settled after applicable deductions merchantReference should be used for merchant-side reconciliation transactionReference is generated by the platform for transaction tracking sourceAccountNumber , sourceAccountName , and sourceBankName provide payer identification details Always implement idempotent webhook handling to prevent duplicate processing Webhook delivery retries may occur if acknowledgement is not returned successfully
• [Resend Accrual Transaction Webhook](https://docs.miden.co/accrual-webhooks/resend-accrual-transaction-webhook.md): Overview This endpoint allows you to resend previously generated collection webhook events by supplying one or more transaction references. It is designed for recovery and replay scenarios where webhook notifications may have failed, timed out, or were not successfully processed by the receiving system. Usage Use this endpoint to: Re-trigger missed collection webhook events. Recover failed webhook deliveries. Synchronize collection transaction status across systems. Replay historical collection notifications. Reconcile missing collection records in downstream services. Test webhook processing workflows using existing transaction references. Expected Behaviour When this endpoint is called: The system validates all supplied transaction references. Previously generated collection webhook events linked to those transactions are re-triggered. Original webhook payloads are resent to the subscribed webhook URL(s). Existing event structures and event types remain unchanged. Failed or missed webhook deliveries can be recovered without creating duplicate transactions. Typical Use Cases Scenario Purpose Webhook timeout Replay webhook after receiver timeout Server downtime Recover events missed during an outage Failed processing Retry events after fixing application errors Data reconciliation Restore missing collection transaction records Testing Replay production-like webhook payloads Notes This endpoint only resends existing collection webhook events. It does not create new collection transactions or generate new webhook events. Multiple transaction references can be supplied in a single request. Ensure idempotent webhook processing on your server to avoid duplicate processing. Invalid or non-existent transaction references may be ignored or return an error depending on implementation. Original webhook payloads and event types remain unchanged during replay.
• [Stablecoin Collection Webhook](https://docs.miden.co/accrual-webhooks/stablecoin-collection-webhook.md): Overview The Stablecoin Inflow webhook notifies your system when a USD collection has been successfully completed through a supported stablecoin wallet. This event is generated when a customer completes a USD checkout transaction using stablecoin as the payment method. The webhook provides the transaction amount, settled amount, references, channel, currency, and collection status required for reconciliation and downstream processing. Usage Use this webhook to: Confirm successful stablecoin-funded USD checkout transactions. Update the corresponding order or payment status in your system. Reconcile the amount received against the original checkout transaction. Track the amount ultimately settled after applicable deductions. Match the transaction using the provided merchant and transaction references. Trigger downstream fulfilment or accounting processes after a successful collection. Expected Behaviour When this webhook is received, your system should: Verify the webhook signature before processing the event. Confirm the event represents a stablecoin collection. Match merchantReference or transactionReference to the corresponding checkout transaction. Confirm the status before marking the payment as completed. Record both transactionAmount and settledAmount for reconciliation. Process the event idempotently using eventId or transactionReference to prevent duplicate processing. Return the expected successful HTTP response after the webhook has been processed. Notes transactionReference should be stored for transaction tracking, support, and reconciliation. merchantReference can be used to correlate the webhook with the merchant's original checkout request. transactionAmount represents the original transaction amount, while settledAmount represents the amount settled for the transaction. Webhook events may be retried; your integration should therefore process them idempotently. Do not rely on webhook delivery order when updating transaction state.
• [All Customers (copy+1)](https://docs.miden.co/all-customers-copy-1.md): ### Description This endpoint retrieves a list of all customers (cardholders) within the system, along with their associated card details. Each customer record includes: * Personal and contact information * Identification details * Account status * A list of cards issued to the customer (`customerCards`) This provides a **comprehensive view of customers and their cards in a single response**. ### Usage Use this endpoint when you need to: * Retrieve a **full list of customers** in your system * View **cards associated with each customer** * Perform **reporting, audits, or administrative operations** * Support **customer service workflows** (e.g., viewing customer profiles and cards) * Search or filter customers using query parameters
• [Decrypt Encrypted Card Details (copy)](https://docs.miden.co/decrypt-encrypted-card-details-copy.md): To strengthen the protection of sensitive cardholder information, Miden returns full card details— PAN, expiry date, and CVV —in encrypted form. This section explains how to decrypt the SecureCardDetails value returned in the API response using the AES encryption standard. Overview: The encrypted card details are returned in the SecureCardDetails field of the API response. The data is encrypted using AES encryption with a 128-bit key. This ensures that the cardholder information is securely transmitted while allowing you to decrypt it when needed. FLOW/DIAGRAM 1. Encrypted Payload Format The SecureCardDetails field in the API response contains the AES-encrypted card details as a Base64-encoded string . The structure of the original JSON before encryption is as follows: { "CardNumber": "XXXXXXXXXXXXXXXX", "Expiration": "MM/YY", "SecurityCode": "XXX" } 2. Encryption Standard The encryption follows the AES standard with the following parameters: Algorithm: AES (RijndaelManaged) Mode: CBC (Cipher Block Chaining) Padding: PKCS7 Block Size: 128-bit Key & IV: Derived from your registered ClientId: Key: The first 16 characters of your ClientId IV (Initialization Vector): The last 16 characters of your ClientId 3. Decryption Example Below is a sample method in C, Java, Python, PHP, GO & Javascript, for decrypting the Base64-encoded AES-encrypted string: public class FullCardDetails { public string CardNumber { get; set; } public string SecurityCode { get; set; } public string Expiration { get; set; } } FullCardDetails DecryptStringAES(string cipherText, string clientId) { var key = clientId[..16]; var iv = clientId[^16..]; var keybytes = Encoding.UTF8.GetBytes(iv); var secret = Encoding.UTF8.GetBytes(key); var encrypted = Convert.FromBase64String(cipherText); var decriptedFromJavascript = DecryptStringFromBytes(encrypted, keybytes, secret); return JsonConvert.DeserializeObject(decriptedFromJavascript); } string DecryptStringFromBytes(byte[] cipherText, byte[] key, byte[] iv) { // Check arguments. if (cipherText == null || cipherText.Length <= 0) { throw new ArgumentNullException("cipherText"); } if (key == null || key.Length <= 0) { throw new ArgumentNullException("key"); } if (iv == null || iv.Length <= 0) { throw new ArgumentNullException("key"); } // Declare the string used to hold // the decrypted text. string plaintext = null; // Create an RijndaelManaged object // with the specified key and IV. using (var rijAlg = new RijndaelManaged()) { //Settings rijAlg.Mode = CipherMode.CBC; rijAlg.Padding = PaddingMode.PKCS7; rijAlg.FeedbackSize = 128; rijAlg.Key = key; rijAlg.IV = iv; // Create a decrytor to perform the stream transform. var decryptor = rijAlg.CreateDecryptor(rijAlg.Key, rijAlg.IV); try { // Create the streams used for decryption. using (var msDecrypt = new MemoryStream(cipherText)) { using (var csDecrypt = new CryptoStream(msDecrypt, decryptor, CryptoStreamMode.Read)) { using (var srDecrypt = new StreamReader(csDecrypt)) { // Read the decrypted bytes from the decrypting stream // and place them in a string. plaintext = srDecrypt.ReadToEnd(); } } } } catch { plaintext = "keyError"; } } return plaintext; } import javax.crypto.Cipher; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; import com.fasterxml.jackson.databind.ObjectMapper; import java.util.Base64; public class FullCardDetails { public String CardNumber; public String SecurityCode; public String Expiration; } public class Decryptor { public static FullCardDetails decryptStringAES(String cipherText, String clientId) throws Exception { byte[] key = clientId.substring(clientId.length() - 16).getBytes("UTF-8"); // Secret byte[] iv = clientId.substring(0, 16).getBytes("UTF-8"); // Key Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); SecretKeySpec keySpec = new SecretKeySpec(key, "AES"); IvParameterSpec ivSpec = new IvParameterSpec(iv); cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec); byte[] encrypted = Base64.getDecoder().decode(cipherText); byte[] decryptedBytes = cipher.doFinal(encrypted); String decryptedJson = new String(decryptedBytes); return new ObjectMapper().readValue(decryptedJson, FullCardDetails.class); } } import json from base64 import b64decode from Crypto.Cipher import AES from Crypto.Util.Padding import unpad def decrypt_string_aes(cipher_text, client_id): iv = client_id[:16].encode() key = client_id[-16:].encode() encrypted_bytes = b64decode(cipher_text) cipher = AES.new(key, AES.MODE_CBC, iv) decrypted = unpad(cipher.decrypt(encrypted_bytes), AES.block_size) return json.loads(decrypted.decode()) # Example usage: # result = decrypt_string_aes(cipherText, clientId) # print(result['CardNumber'], result['SecurityCode'], result['Expiration']) function decryptStringAES($cipherText, $clientId) { $iv = substr($clientId, 0, 16); $key = substr($clientId, -16); $cipherBytes = base64_decode($cipherText); $decrypted = openssl_decrypt($cipherBytes, 'AES-128-CBC', $key, OPENSSL_RAW_DATA, $iv); if ($decrypted === false) { return "keyError"; } return json_decode($decrypted, true); } import ( "crypto/aes" "crypto/cipher" "encoding/base64" "encoding/json" "errors" ) type FullCardDetails struct { CardNumber string `json:"CardNumber"` SecurityCode string `json:"SecurityCode"` Expiration string `json:"Expiration"` } func DecryptStringAES(cipherText string, clientId string) (*FullCardDetails, error) { iv := []byte(clientId[:16]) key := []byte(clientId[len(clientId)-16:]) encrypted, _ := base64.StdEncoding.DecodeString(cipherText) block, err := aes.NewCipher(key) if err != nil { return nil, err } if len(encrypted)%aes.BlockSize != 0 { return nil, errors.New("ciphertext not a multiple of block size") } mode := cipher.NewCBCDecrypter(block, iv) decrypted := make([]byte, len(encrypted)) mode.CryptBlocks(decrypted, encrypted) // remove PKCS7 padding padLen := int(decrypted[len(decrypted)-1]) decrypted = decrypted[:len(decrypted)-padLen] var details FullCardDetails err = json.Unmarshal(decrypted, &details) if err != nil { return nil, err } return &details, nil } const crypto = require('crypto'); function decryptStringAES(cipherText, clientId) { const iv = Buffer.from(clientId.slice(0, 16), 'utf8'); const key = Buffer.from(clientId.slice(-16), 'utf8'); const encrypted = Buffer.from(cipherText, 'base64'); try { const decipher = crypto.createDecipheriv('aes-128-cbc', key, iv); let decrypted = decipher.update(encrypted); decrypted = Buffer.concat([decrypted, decipher.final()]); return JSON.parse(decrypted.toString()); } catch (err) { return "keyError"; } } SAMPLE: Sample Value Client ID GEORGEDAUGHTERS4BF84D67844F4A3E94E884719E6DBDDF First 16 characters GEORGEDAUGHTERS4 Last 16 characters 3E94E884719E6DBDDF Encryted Card Details "sxffEgIcRfEtc+ksicd/ednipGRhwtBZYOowlrFx9uWpJDq8Q0AYsswX2c9WCAunG5PSeYYEJwYD6h2Rbi0rp4KUvW3W5KqAJ9Obe9euN30=" Decrypted Card Details { "cardNumber": "5319933706924864", "securityCode": "958", "expiration": "0528" } 4. Security Best Practices While handling decrypted card data, ensure you follow these key security practices: Never log decrypted card details. Store only the necessary data and ensure compliance with PCI-DSS and other relevant standards. Keep your ClientId private and protect it at all times.
• [Lite Card (copy+1)](https://docs.miden.co/lite-card-copy-1.md): ##### **Description:** This endpoint allows you to issue a **Lite Card** for a customer with a predefined balance and a fixed number of allowed swipes. Lite Cards are designed for **controlled, limited-use scenarios**. They cannot be topped up after issuance and are intended to terminate automatically once either of the following happens: * the configured **swipe count** is exhausted, or * the card **runs out of balance** This makes Lite Cards suitable for one-off or tightly restricted spending use cases where card usage must end automatically based on spend or usage count. **Usage Options:** Use this endpoint when you need to issue a card that should operate within strict limits and terminate automatically without further funding. Lite Cards are best suited for use cases such as: * vouchers or benefit disbursements * one-time or short-term spending programs * controlled customer incentives * fixed-purpose cards with limited transaction count For example, if a Lite Card is issued with: * a **card balance** of `$20`, and * a **swipe count** of `3` the cardholder can use the card up to **3 times**, and the card will terminate on the **third successful swipe** or earlier if the **balance is depleted before then**. Because Lite Cards **cannot be topped up**, they are ideal where spend control and automatic card closure are required.
• [Lite Card (copy+1)](https://docs.miden.co/lite-card-copy-1-1.md): ##### **Description:** This endpoint allows you to issue a **Lite Card** for a customer with a predefined balance and a fixed number of allowed swipes. Lite Cards are designed for **controlled, limited-use scenarios**. They cannot be topped up after issuance and are intended to terminate automatically once either of the following happens: * the configured **swipe count** is exhausted, or * the card **runs out of balance** This makes Lite Cards suitable for one-off or tightly restricted spending use cases where card usage must end automatically based on spend or usage count. **Usage Options:** Use this endpoint when you need to issue a card that should operate within strict limits and terminate automatically without further funding. Lite Cards are best suited for use cases such as: * vouchers or benefit disbursements * one-time or short-term spending programs * controlled customer incentives * fixed-purpose cards with limited transaction count For example, if a Lite Card is issued with: * a **card balance** of `$20`, and * a **swipe count** of `3` the cardholder can use the card up to **3 times**, and the card will terminate on the **third successful swipe** or earlier if the **balance is depleted before then**. Because Lite Cards **cannot be topped up**, they are ideal where spend control and automatic card closure are required.
• [Issue Retail Card (copy+2)](https://docs.miden.co/issue-retail-card-copy-2.md): Description: This endpoint allows you to issue a corporate card—either enabled for contactless payment or not—to a registered business entity. Corporate cards can be used for business expenses and configured with various controls depending on the card type. Usage Options: Use this endpoint when you need to create and fund a new corporate card. Use only the basic fields in the payload (omit contactless-specific fields like contactlessPayment , cardLimits , etc.). Add the following additional fields to enable contactless payment features and advanced controls: contactlessPayment (boolean) cardLimits (object) whiteListedMccs, blackListedMccs (arrays)
• [Issue Corporate Card (copy)](https://docs.miden.co/issue-corporate-card-copy.md): Description This endpoint allows you to issue a corporate card—either enabled for contactless payment or not—to a registered business entity. Corporate cards can be used for business expenses and configured with various controls depending on the card type. Tokenized cards support advanced controls such as: Contactless (cardless) payments Transaction limits MCC (Merchant Category Code) whitelisting/blacklisting Cards not enabled for contactless payment are simpler and intended for standard corporate spending without advanced controls. When to Use Use this endpoint when you need to create and fund a new corporate card for a business customer.
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays)
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy-1.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays)
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy-3.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays) ### **Request**
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy-4.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays) ### **Request**
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy-5.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays) ### **Request**
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy-6.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays) ### **Request**
• [Issue Corporate Card (copy)](https://docs.miden.co/issue-corporate-card-copy-1.md): Description This endpoint allows you to issue a corporate card—either enabled for contactless payment or not—to a registered business entity. Corporate cards can be used for business expenses and configured with various controls depending on the card type. Tokenized cards support advanced controls such as: Contactless (cardless) payments Transaction limits MCC (Merchant Category Code) whitelisting/blacklisting Cards not enabled for contactless payment are simpler and intended for standard corporate spending without advanced controls. When to Use Use this endpoint when you need to create and fund a new corporate card for a business customer.
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy-7.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays) ### **Request**
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy-8.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays) ### **Request**
• [Issue Retail Card (copy)](https://docs.miden.co/issue-retail-card-copy-9.md): ##### **Description:** This endpoint allows you to issue a USD retail card—either as a **Virtual Card** or **Contactless Virtual Card**, depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. **Usage Options:** * Use only the basic fields in the payload (omit contactless-specific fields like `contactlessPayment`, `cardLimits`, etc.). * Add the following additional fields to enable contactless payment features and advanced controls: * `contactlessPayment` (boolean) * `cardLimits` (object) * `whiteListedMccs`, `blackListedMccs` (arrays) ### **Request**
• [Card KYC](https://docs.miden.co/cards/card-kyc.md): Overview The Card KYC APIs enable you to verify the identity of individual customers and the registration details of business customers before issuing payment cards. A successful verification returns a Customer ID , which is required for card issuance and subsequent card management operations. Miden supports multiple KYC and KYB verification methods. Based on the customer type and identification method provided, the appropriate verification flow is selected automatically. Individual customers can be verified using one of the following identification methods: Passport Driver's License National ID (where supported) Bank Verification Number (BVN) National Identification Number (NIN) Business customers are verified using their registered business information through the Business KYC (KYB) flow. The Card KYC APIs provide endpoints to: Submit KYC verification requests Retrieve the current status of an existing verification Receive verification updates through webhooks Available Verification Methods Individual Verification Supports the following verification methods: Passport Verification Driver's License Verification National ID Verification (where supported) Bank Verification Number (BVN) National Identification Number (NIN) Business Verification Supports: Know Your Business (KYB) Verification Flow The typical verification process is: Submit a Card KYC or Business KYB request. Miden determines the appropriate verification flow based on the customer type and identification method. Complete the verification process. Upon successful verification, a Customer ID is returned. Use the returned Customer ID to issue a card. Manage the card using the available Card Management APIs. API Endpoints Endpoint Description Submit Individual KYC (Passport / Driver's License / National ID) Verifies an individual customer using a supported government-issued identification document such as a Passport, Driver's License, or National ID. Submit Individual KYC (BVN Verification) Verifies an individual customer using their Bank Verification Number. Submit Individual KYC (NIN Verification) Verifies an individual customer using their National Identification Number. Submit Business KYC (KYB Verification) Verifies a registered business using its business registration information. Get Card KYC Status Retrieves the latest status of a previously submitted KYC verification. Verification Statuses A verification request may return one of the following statuses during its lifecycle: Status Description Initiated The verification request has been received and accepted for processing. Pending Verification is currently in progress. Approved The customer has successfully passed verification. Rejected The customer did not pass verification.
  • [Individual KYC — Identity Document Verification](https://docs.miden.co/cards/card-kyc/individual-kyc-identity-document-verification.md): Description This endpoint verifies an individual customer's identity using a supported government-issued identification document. Upon successful verification, Miden returns a Customer ID , which is required for card issuance and subsequent card management operations. Usage Use this endpoint to verify an individual customer using a supported government-issued identification document. This verification method can be used when the customer is verifying with any supported identity document, including: International Passport Driver's License National ID Voter's Card Ghana Card Other supported government-issued identity documents (country dependent) This endpoint is suitable for both Nigerian and non-Nigerian customers, provided the selected identification document is supported. Notes Government ID verification is asynchronous. A clear image of the selected government-issued identity document must be provided. The document image may be supplied as a Base64 string or data URI. The returned kycToken can be used to retrieve the latest verification status until verification is completed. Card KYC webhooks provide status updates such as kyc.initiated , kyc.pending , kyc.approved , and kyc.rejected . Do not submit BVN or NIN through this document-verification payload. Treat document images, identity numbers, and the kycToken as sensitive information. The Reference header should be unique for each new submission. Supported Document Types Identification Method Supported International Passport ✓ Driver's License ✓ National ID ✓ Voter's Card ✓ Ghana Card ✓ Other Government-issued National IDs ✓ (country dependent)
  • [Individual KYC — BVN Verification](https://docs.miden.co/cards/card-kyc/individual-kyc-bvn-verification.md): Description This endpoint verifies an individual Nigerian customer using their Bank Verification Number. BVN verification does not require a document upload and is processed synchronously. The API returns an immediate verification result. The verification is approved when either the verified BVN holder’s first name or last name matches the name supplied in the request. Usage Use this endpoint when the customer is an individual and will be verified using a BVN. The customer’s address country must be supplied as one of the following: NGA NG Nigeria Notes BVN verification is synchronous. idFrontImage is not required for BVN verification. idType must be BVN . The customer’s country must be NGA , NG , or Nigeria . Verification is approved when either the verified first name or last name matches the supplied customer name. Store the returned customerId , kycToken , and clientReference . Do not log or expose the customer’s full BVN. Use a unique Reference header for each new submission.
  • [Individual KYC — NIN Verification](https://docs.miden.co/cards/card-kyc/individual-kyc-nin-verification.md): Description This endpoint verifies an individual Nigerian customer using their National Identification Number. NIN verification does not require a document upload and is processed synchronously. The customer’s first name, last name, and date of birth are required. Usage Use this endpoint when the customer is an individual and will be verified using a NIN. The customer’s address country must be supplied as one of the following: NGA NG Nigeria Notes NIN verification is synchronous. No identity-document upload is required. idType must be NIN . firstName , lastName , and dateOfBirth are mandatory. dateOfBirth must be provided in YYYY-MM-DD format. The customer’s country must be NGA , NG , or Nigeria . Store the returned customerId , kycToken , and clientReference . Do not log or expose the customer’s full NIN. Use a unique Reference header for each new submission.
  • [Business KYC — KYB Verification](https://docs.miden.co/cards/card-kyc/business-kyc-kyb-verification.md): Description This endpoint submits a business customer’s registration and address details for Know Your Business verification. Business verification is processed asynchronously. A successful request returns a kycToken and an initial KYC status of Initiated . The final verification result is provided through the Card KYC webhook or retrieved through the Get Card KYC Status endpoint. Usage Use this endpoint to verify a registered business before providing access to card services. The request must include the registered business name, registration number, and business address. Notes customerType must be Business . businessKyc must be supplied. registrationNumber is mandatory. Business verification is asynchronous. Use the returned kycToken to retrieve the latest status. Card KYC webhooks provide subsequent status updates. Do not include individualKyc in the business request. The business address should correspond to the registered or principal business location. Store the returned customerId , kycToken , and clientReference . Use a unique Reference header for each new submission.
  • [Simulate Card KYC Webhook](https://docs.miden.co/cards/card-kyc/simulate-card-kyc-webhook-1.md): Description This endpoint simulates Card KYC webhook events for testing webhook integrations. Specify the desired verification status in the request body to generate the corresponding webhook payload that would normally be delivered to your configured webhook endpoint. Usage Use this endpoint to: Test your Card KYC webhook integration without performing an actual verification. Simulate different verification outcomes ( Initiated , Pending , Approved , or Rejected ). Validate your application's webhook handling logic. Test rejection handling using custom rejection reasons and labels. Verify end-to-end KYC workflows in development and staging environments. Supported Statuses Status Additional Fields Initiated None Pending None Approved None Rejected rejectReason , rejectLabels Notes rejectReason and rejectLabels are required only when simulating a Rejected status. The generated webhook payload matches the production webhook format for the selected status. This endpoint is intended for testing and development purposes only. Example values BLURRY_PHOTO EXPIRED_DOCUMENT DOCUMENT_UNREADABLE FACE_MISMATCH DOCUMENT_CROPPED
  • [Get Card KYC](https://docs.miden.co/cards/card-kyc/get-card-kyc.md): Description Retrieves the details and current status of a previously submitted Card KYC request using the clientReference supplied during the original verification request. The response includes the verification status, Customer ID (if available), KYC token, and the submitted customer information. Usage Use this endpoint to: Retrieve a Card KYC record using your own client reference. Check the current verification status of a KYC request. Obtain the generated Customer ID after successful verification. Retrieve the submitted KYC information for reconciliation or audit purposes. Notes For successful verifications, the customerId should be stored and used for subsequent card issuance requests. The response structure differs based on the customerType . Business KYC requests return a businessKyc object instead of individualKyc . This endpoint returns the latest available status of the KYC request associated with the supplied clientReference . If the verification is still in progress, the kycStatus will reflect the current lifecycle state.
• [Card Issuance](https://docs.miden.co/cards/miden-managed-authorizations/card-issuance.md): This folder contains the endpoints used to issue and manage virtual cards for both individual users and businesses. The APIs support issuing Retail Cards, Lite Cards, Corporate Cards, and Re-Issued Cards , allowing you to tailor card experiences to different customer needs. All cards issued through these endpoints are virtual by default , but they may optionally support contactless payment functionality depending on the configuration provided in the request payload. Su pported card types include: Virtual Cards – Standard virtual cards designed for online transactions. Contactless Virtual Cards – Virtual cards that support digital wallet integrations such as Apple Pay and Google Pay, enabling contactless payments. These endpoints allow you to: Issue cards to individual users or businesses Configure card limits and spending controls Enable contactless payments and digital wallet provisioning Apply merchant category restrictions (MCC whitelisting or blacklisting) Manage reloadable and non-reloadable card types The available endpoints in this folder include: Issue Retail Card Issue Lite Card Issue Corporate Card Re-Issue Card Together, these APIs provide flexible card issuance capabilities for a wide range of fintech use cases,
  • [Issue Retail Card](https://docs.miden.co/cards/miden-managed-authorizations/card-issuance/issue-retail-card.md): Description: This endpoint allows you to issue a USD retail card—either as a Virtual Card or Contactless Virtual Card , depending on your use case. All cards are virtual, but contactless capabilities can be optionally enabled through specific payload fields. Usage Options: Use only the basic fields in the payload (omit contactless-specific fields like contactlessPayment , cardLimits , etc.). Add the following additional fields to enable contactless payment features and advanced controls: contactlessPayment (boolean) cardLimits (object) whiteListedMccs , blackListedMccs (arrays)
  • [Corporate Card](https://docs.miden.co/cards/miden-managed-authorizations/card-issuance/corporate-card.md): Description: This endpoint allows you to issue a corporate card—either enabled for contactless payment or not—to a registered business entity. Corporate cards can be used for business expenses and configured with various controls depending on the card type. Usage Options: Use this endpoint when you need to create and fund a new corporate card. Use only the basic fields in the payload (omit contactless-specific fields like contactlessPayment , cardLimits , etc.). Add the following additional fields to enable contactless payment features and advanced controls: contactlessPayment (boolean) cardLimits (object) whiteListedMccs , blackListedMccs (arrays) Notes for Issuing Corporate Cards RC Number: Requirement: The RC number provided must be your valid registered company number. Consequences of Invalid RC Number: If the RC number is invalid, the corporate card issuance process will fail. Ensure that the RC number is accurate and up-to-date to avoid errors in card creation. Card Address: Requirement: A valid business address must be provided for the organization issuing the corporate card. Country Availability: Corporate cards are available to businesses in supported countries, provided the business is not located in a sanctioned jurisdiction and has completed the required KYB verification. Usage: The organization address on record may be used as part of the corporate card issuance and verification process. Registration: To register or update an address for your organization, you need to contact Miden Support. Ensure that the address on file is correct and up-to-date to facilitate smooth card issuance.
  • [Lite Card](https://docs.miden.co/cards/miden-managed-authorizations/card-issuance/lite-card.md): Description This endpoint issues a Lite Card, a restricted-use virtual card designed for controlled spending. Users can define the card balance, usage count, expiration date, and termination date during card creation. Lite Cards cannot be topped up after issuance. Usage Use this endpoint to: Issue single-use or limited-use virtual cards. Control how many times a card can be used. Set spending limits and card validity periods. Create temporary cards for subscriptions, gifts, vendors, or one-time payments. Notes Lite Cards cannot be topped up after issuance. swipeCount controls the total number of permitted transactions. The card automatically becomes inactive after the terminateDate . Ensure the funding wallet has sufficient balance before issuing a card. Supported card brands may vary by region and configuration.
  • [Re-issue Card](https://docs.miden.co/cards/miden-managed-authorizations/card-issuance/re-issue-card.md): Description: This endpoint is used to issue additional cards—both contactless and non-contactless —for an existing cardholder identified by their cardCustomerId . It enables users to generate multiple cards under the same customer profile. The sharedBalance option enables you to link the new card you are about to create to the balance of an already existing card under the same cardCustomerId , creating a multi-card setup that draws from a single balance pool. Usage Use this endpoint when: You want to issue multiple cards to the same customer (e.g., departmental use, family/team cards). You need to control spending with card limits and MCC whitelists/blacklists, only available to tokenized cards. You want newly issued cards to share a balance with an existing card (by passing sharedBalance: true and a valid cardId of the card whose balance will be shared). initialBalance If sharedBalance is false , then this field is not passed. address This is optional. If not passed, address used to create initial card will be used. cardId if sharedBalance is false , then this field is not passed
• [Card Transactions](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions.md): Overview The Card Transactions section covers endpoints related to card activity, including authorizations, captures, refunds, and transaction history. It allows merchants to track the full lifecycle of card payments, monitor transaction status, and perform reconciliation using consistent transaction references.
  • [Authorization](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/simulations/authorization.md): This endpoint is used to Issue a new virtual card to a user. This should be used for new customers without an existing card. The response object contains the customer Id that can be used subsequently to re-issue or create more cards to the same customer.
  • [Settlement](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/simulations/settlement.md): This endpoint is used to Issue a new permanent virtual card to a user. This should be used for new customers without an existing card. The response object contains the customer Id that can be used subsequently to re-issue or create more cards to the same customer. Field Name Field Description Field Type Is Manadatory firstName First name of the customer String True lastName Last name of the customer String True phone Phone number of the customer String True address1 Primary address of the customer. Only letters, numbers and these special characters ,.- String True address2 Secondary address of the customer. Only letters, numbers and these special characters ,.- String False city City where the customer lives. Only letters, hyphens, and punctuation allowed String True state State where the customer lives String True zipcode Zipcode of the customer’s address. The Zipcode must be between 1 and 10 characters long. String True country Country of the customer’s address. Only alpha-2 digit country code is allowed String True idNumber ID number of the customer String True idType Type of ID of the customer String True customerBvn Bank Verification Number of the customer (For Nigerian Customers) String (Only True for Nigerian customers) initialBalance Balance on the card once issued(This amount will be debited from your float USD wallet) double True cardBrand Brand of the card of the customer (Visa or Master) String True
  • [Decline](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/simulations/decline.md): This endpoint is used to Issue a new permanent virtual card to a user. This should be used for new customers without an existing card. The response object contains the customer Id that can be used subsequently to re-issue or create more cards to the same customer.
  • [Refund](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/simulations/refund.md): This endpoint is used to Issue a new permanent virtual card to a user. This should be used for new customers without an existing card. The response object contains the customer Id that can be used subsequently to re-issue or create more cards to the same customer. Field Name Field Description Field Type Is Manadatory firstName First name of the customer String True lastName Last name of the customer String True phone Phone number of the customer String True address1 Primary address of the customer. Only letters, numbers and these special characters ,.- String True address2 Secondary address of the customer. Only letters, numbers and these special characters ,.- String False city City where the customer lives. Only letters, hyphens, and punctuation allowed String True state State where the customer lives String True zipcode Zipcode of the customer’s address. The Zipcode must be between 1 and 10 characters long. String True country Country of the customer’s address. Only alpha-2 digit country code is allowed String True idNumber ID number of the customer String True idType Type of ID of the customer String True customerBvn Bank Verification Number of the customer (For Nigerian Customers) String (Only True for Nigerian customers) initialBalance Balance on the card once issued(This amount will be debited from your float USD wallet) double True cardBrand Brand of the card of the customer (Visa or Master) String True
  • [All Card Transactions](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/transactions/all-card-transactions.md): Description Retrieves a paginated list of transactions associated with issued cards. This endpoint provides visibility into all card activity, including authorizations, settlements, declines, top-ups, withdrawals, transfers, and cross-border transactions. Each transaction record includes transaction status, amounts, and post-transaction balances. Results can be filtered using multiple parameters such as card identifiers, transaction type, status, and date range. Usage This endpoint supports flexible querying, allowing you to retrieve: all transactions across cards transactions for a specific card transactions within a defined date range transactions filtered by type or status
  • [Card Transaction Status](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/transactions/card-transaction-status.md): Description Retrieves the current status and details of a specific card transaction using its transaction reference. This endpoint returns a single transaction record, including the transaction type, status, amount, merchant details, card identifiers, and related authorization metadata. It is useful for checking the outcome of a previously initiated transaction without retrieving the full transaction list. Usage Use this endpoint to: Check the status of a specific transaction using its reference Confirm whether a transaction is pending, successful, declined, or otherwise processed Investigate transaction details for support, reconciliation, or operational review Retrieve merchant, amount, and card information tied to a known transaction Track the outcome of card funding, withdrawals, authorizations, and other card operations This endpoint is best used when you already have a transactionReference and need the details for that single transaction.
  • [Card Top Up](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/transactions/card-top-up.md): Description Credits funds from your wallet to a card, increasing the card’s available balance. This operation debits the specified amount from the source wallet (your wallet) and applies it to the target card. Currency conversion may occur depending on the wallet and card currencies. Usage Use this endpoint to: fund a card for spending increase the available balance on a card prepare a card for transactions retry previously failed transactions after funding This is a wallet → card operation.
  • [Card Withdrawal](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/transactions/card-withdrawal.md): Description Withdraws funds from a card and returns them to the linked wallet. This operation debits the specified amount from the card and credits it back to the wallet. It is typically used when funds need to be moved off a card after funding, reallocation, or operational correction. Cards must maintain the required minimum balance after withdrawal. Usage Use this endpoint to: move funds from a card back to a wallet reduce the balance on a card that is no longer needed or that cardholder owes you. correct funding errors recover unused funds from a card This is a card → wallet operation.
  • [Reprocess Pending Cross Border](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/transactions/reprocess-pending-cross-border.md): Description This endpoint allows customers to re-process pending cross-border charges for the current month. It ensures that once sufficient funds are available on the card, previously failed cross-border transactions are queued for successful re-processing. Usage Trigger this endpoint when a cardholder has added sufficient funds to their card, and you need to attempt processing previously failed cross-border transactions for the current billing period. This action does not re-process successful transactions, only those marked as pending due to insufficient funds or similar issues. Notes Only pending cross-border transactions are reprocessed Transactions already successfully processed are not affected Ensure the card has sufficient balance before calling this endpoint Reprocessing applies to transactions within the current billing period only Use transaction status endpoints to verify the outcome after reprocessing
  • [Card to Card Transfer](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/transactions/card-to-card-transfer.md): Description Transfers funds from one card to another card within the same card ecosystem. This endpoint enables internal card-to-card movement of funds without using external payment rails. The specified amount is debited from the source card and credited to the beneficiary card. Usage Use this endpoint when you need to: move funds between two cards reallocate balances across cards transfer funds between cards owned by the same cardholder or within the same managed ecosystem support internal budget redistribution or card funding adjustments This is a card → card operation.
  • [Get Rate](https://docs.miden.co/cards/miden-managed-authorizations/card-transactions/rates/get-rate.md): Description Retrieves the current exchange rate between a specified source currency and the system’s base settlement currency (USD). The response includes both buy rate and sell rate , which are used for currency conversions during card funding, withdrawals, and transactions. Usage Use this endpoint to: determine the exchange rate before performing a card top-up or withdrawal calculate expected debit or credit amounts during currency conversion display real-time FX rates to users.
• [Card Info](https://docs.miden.co/cards/miden-managed-authorizations/card-info.md): Overview The Card Info section provides endpoints for retrieving card-related details, including card metadata, status, limits, and securely encrypted card information where applicable. It enables merchants to view and manage card attributes required for operations such as display, validation, and controlled usage.
  • [Card Details: Mask Pan (deprecated)](https://docs.miden.co/cards/miden-managed-authorizations/card-info/card-details-mask-pan-deprecated.md): Description This endpoint retrieves card details for a specific card using its unique identifier, returning the masked PAN version of the card number. The masked PAN ensures that sensitive card information is protected by only exposing partial digits (typically the first 6 and last 4), making it safe for display and general usage. This endpoint does not return full card details. For full PAN retrieval, use the Get Card Details (Full PAN) endpoint and decrypt secured card details accordingly. Usage Use this endpoint when you need to: Display card information in your application (e.g., dashboards, user interfaces) Retrieve non-sensitive card details for operational or reporting purposes Safely reference a card without exposing full card data
  • [Card Details: Full Pan (deprecated)](https://docs.miden.co/cards/miden-managed-authorizations/card-info/card-details-full-pan-deprecated.md): Description This endpoint retrieves the full card details for a specific card using its unique identifier. Unlike the masked PAN version of this endpoint, this response includes the full card number (PAN) , security code , and expiration details in the data object. It also returns a secureCardDetails field containing the card details in encrypted form for secure handling where required. This endpoint should only be used in authorized workflows that require access to sensitive card data. Usage Use this endpoint when you need access to the complete card details for operational or authorized card workflows, such as: displaying full card details in a secure environment card provisioning secure backend card operations Because this endpoint returns sensitive card information, it should be used only when necessary and handled in a PCI-compliant manner.
  • [Card Balance](https://docs.miden.co/cards/miden-managed-authorizations/card-info/card-balance.md): Overview This endpoint retrieves the current available balance of a specific card. It allows merchants and applications to check how much funding is currently accessible on a card before initiating transactions, withdrawals, purchases, or transfers. Usage The Get Card Balance endpoint is used to fetch the real-time available balance associated with a card. This helps applications validate spending limits, confirm sufficient funds before processing transactions, and display up-to-date card balances to users. Expected Behaviour When this endpoint is called: The system validates the authorization credentials The specified cardId is verified The current available balance for the card is retrieved The API returns the available balance alongside the request status and response code Notes The returned balance represents the currently available spendable amount on the card Balance values may change in real time due to pending or completed transactions Always validate isSuccessful before using the returned balance value A responseCode of 000 indicates a successful request Ensure the requesting application has permission to access the specified card information
  • [Masked PAN](https://docs.miden.co/cards/miden-managed-authorizations/card-info/masked-pan.md): Overview This endpoint retrieves the masked Primary Account Number (PAN) details and configuration information for a specific card. It provides card metadata such as card brand, currency, card limits, expiration details, status, and administrative restrictions without exposing sensitive full PAN information. Usage The Get Masked PAN Details endpoint is used to securely retrieve non-sensitive card information for display, monitoring, validation, and operational purposes. Applications can use this endpoint to display card details to users, validate card status, review spending limits, and confirm card configuration without exposing the complete card number. Expected Behaviour When this endpoint is called: The system validates authorization credentials The specified cardId is verified Card metadata and masked PAN details are retrieved Spending limits and administrative restrictions are returned The API responds with card configuration details and request status Notes This endpoint does not expose the full PAN for security reasons isPhysical differentiates physical cards from virtual cards blockedByAdmin indicates whether administrative restrictions are active midWhitelist and midBlacklist may be used for merchant-level transaction controls A responseCode of 000 indicates a successful request Always validate isSuccessful before processing the response Spending limits returned under cardLimits may vary depending on card configuration and policy
  • [Full PAN](https://docs.miden.co/cards/miden-managed-authorizations/card-info/full-pan.md): Overview This endpoint retrieves the complete PAN (Primary Account Number) details of a card, including the full card number, CVV/security code, expiration details, billing information, and card configuration settings. Because this endpoint exposes sensitive cardholder information, access should be strictly controlled and handled in compliance with PCI DSS and other applicable security standards. Usage The Get Full PAN Details endpoint is used when a system or authorized application needs secure access to full card information for payment processing, wallet provisioning, card display, or card management operations. This endpoint should only be accessed in highly secure environments with proper encryption, authorization, and auditing mechanisms in place. Expected Behaviour When this endpoint is called: The system validates all authorization and security credentials The specified cardId is verified Full card details are securely retrieved Billing information and spending limits are included in the response The API returns the card information alongside the request status and response code Notes isPhysical differentiates between physical and virtual cards status indicates whether the card is active or restricted cardLimits define configured spending restrictions billingDetails contains the cardholder billing address associated with the card A responseCode of 000 indicates a successful request Always validate isSuccessful before processing the response Some fields may return null depending on card configuration or data availability
  • [Blocked Cards](https://docs.miden.co/cards/miden-managed-authorizations/card-info/blocked-cards.md): Description This endpoint retrieves a list of cards that have been frozen, or terminated as a result of transaction-related events.These events may include: Insufficient funds Declined transactions Merchant restrictions (e.g., blocked MID) Other authorization or processing failures Each record provides details about the card, the triggering reason, and any resulting balance handling (such as wallet credits after termination). Usage Use this endpoint when you need to: Monitor cards that have been restricted due to transaction activity Investigate failed or declined transactions Track cards impacted by merchant or authorization rules Reconcile balances for cards that were terminated after usage issues Support customer service and dispute resolution workflows Notes The cards array may contain multiple records depending on the query merchantIdentifier may be null if no merchant is associated Timestamps are returned in ISO 8601 format balanceCreditedIntoWallet = true indicates funds were successfully returned to your wallet/position after termination
  • [All Customers](https://docs.miden.co/cards/miden-managed-authorizations/card-info/all-customers.md): Description This endpoint retrieves a list of all customers (cardholders) within the system, along with their associated card details. Each customer record includes: Personal and contact information Identification details Account status A list of cards issued to the customer ( customerCards ) This provides a comprehensive view of customers and their cards in a single response . Usage Use this endpoint when you need to: Retrieve a full list of customers in your system View cards associated with each customer Perform reporting, audits, or administrative operations Support customer service workflows (e.g., viewing customer profiles and cards) Search or filter customers using query parameters
  • [All Cards](https://docs.miden.co/cards/miden-managed-authorizations/card-info/all-cards.md): Description This endpoint retrieves a list of all cards within the system, including their configuration, status, and associated customer information. It provides a comprehensive view of all issued cards, including limits, balances, lifecycle status (active, terminated, etc.), and feature configurations such as wallet support and authentication settings. Usage Use this endpoint when you need to: Retrieve a complete list of cards in your system Monitor card status and lifecycle (active, terminated, cancelled) Track balances, limits, and configurations Support administrative dashboards and reporting Investigate cards using filters such as customer, card ID, or date range This endpoint supports pagination and flexible filtering , allowing you to efficiently query large datasets. Notes All query parameters are optional and may be combined to refine search results. Date filters ( fromDate and toDate ) must be provided in YYYY-MM-DD format. Results are returned in a paginated format. Use pageNumber and pageSize to navigate through multiple pages. If no filters are supplied, the endpoint returns all cards belonging to your organization. Some response fields may return null depending on the card type, configuration, or current lifecycle state.
• [Card Management](https://docs.miden.co/cards/miden-managed-authorizations/card-management.md): Overview The Card Management section includes endpoints used to control and configure card behavior. This includes actions such as blocking or unblocking cards, managing merchant restrictions (whitelist/blacklist), updating limits, and terminating cards. It enables merchants to enforce usage rules and maintain security over issued cards.
  • [Set Card Limit](https://docs.miden.co/cards/miden-managed-authorizations/card-management/set-card-limit.md): Description Updates the spending controls on a specific card by setting the daily & monthly limit and the per-transaction limit . This endpoint is used to restrict how much a card can spend within a day and how much can be spent in a single transaction. It helps enforce card usage policies, spending thresholds, and operational controls for cardholders. Usage Use this endpoint when you need to: control the maximum amount a card can spend in one day restrict the maximum amount allowed per single transaction enforce spend rules for employee, team, or business cards reduce exposure to excessive or unauthorized card usage This is useful for card control, budgeting, employee spend management, and fraud reduction. Notes This endpoint updates spending limits for the specified card only. The dailyLimit controls total spend allowed across all transactions in a single day. The transactionLimit controls the maximum value allowed for any single card transaction. The response data object reflects the updated state of the card after the limit change. monthlyLimit may be returned as 0.0 when no monthly limit is configured. A failed request returns data as null and includes the corresponding failure message and response code.
  • [Set Card Minimum Balance](https://docs.miden.co/cards/miden-managed-authorizations/card-management/set-card-minimum-balance.md): Description Sets or updates the minimum balance required on a specific card. The minimum balance represents the lowest allowed balance that must be maintained on the card. Transactions that would cause the card balance to fall below this value may be declined, depending on configured rules. This endpoint is idempotent — calling it multiple times with the same value will not result in additional changes. Usage Use this endpoint when you need to: enforce a minimum balance threshold on a card update an existing minimum balance requirement (Miden enforces a minimum balance of $1. Your configuration with this endpoint cannot be lower than $1 remove a minimum balance restriction by setting the value to 0 This is a card balance control operation. Notes Setting minimumBalance to 0 effectively removes the minimum balance restriction. The minimum balance rule may cause transactions to be declined if the resulting balance falls below the configured value. This feature may not be supported for all card programs (BINs). The endpoint is idempotent — repeated requests with the same value will return a success response without additional changes. No card details are returned in the response — only operation status is provided.
  • [Activate/Deactivate Card](https://docs.miden.co/cards/miden-managed-authorizations/card-management/activate-deactivate-card.md): Description Activates or deactivates a card by toggling its current usage status. This endpoint is used to freeze or unfreeze a card without terminating it. Deactivating a card temporarily prevents it from being used for transactions, while activating it restores the card for normal use. This operation is useful for temporary card control, fraud prevention, security response, or operational card management. Usage Use this endpoint when you need to: temporarily disable a card to prevent further usage re-enable a previously suspended card freeze a card that is suspected to be compromised unfreeze a card after review or customer confirmation This is a card status management operation. Notes Set activated to false to deactivate or freeze the card. Set activated to true to activate or unfreeze the card. Deactivating a card does not terminate it; it only changes its usage status. The response data object reflects the updated state of the card after the operation. The status field shows the effective result of the request, such as Card - Suspended or Card - Active . No funds are moved and no balance adjustment is performed during this operation. Card limits remain unchanged by this request.
  • [Terminate Card](https://docs.miden.co/cards/miden-managed-authorizations/card-management/terminate-card.md): Description Terminates a card permanently and prevents it from being used for any future transactions. This endpoint is used to permanently deactivate a card and close its active lifecycle. Once terminated, the card cannot be reactivated for use. The operation returns the updated card state, including its termination timestamp, final available balance, and related card metadata. This is a permanent card lifecycle action and should be used only when the card is no longer needed or must be permanently retired. Usage Use this endpoint when you need to: permanently stop a card from being used close a card that should no longer remain active retire a card after operational, compliance, or security review ensure a terminated card cannot be reactivated for future spending This is a card termination operation. Notes This endpoint permanently terminates the specified card. A terminated card cannot be used for future transactions. The response data object reflects the final state of the card after termination. terminateDate is populated only when the termination is successful. In the sample success response, availableBalance becomes 0.0 after termination, while balanceBeforeTermination shows the balance that existed before the operation was completed. If the card has already been terminated, the request fails and returns data as null . The status field in the success response reflects the post-termination card state.
  • [Regularize Terminated Card](https://docs.miden.co/cards/miden-managed-authorizations/card-management/regularize-terminated-card.md): Description Regularizes a terminated card that has a negative balance at the time of termination. This is a post-termination financial adjustment operation and applies only to terminated cards with outstanding negative balances.
  • [Blacklist Merchant](https://docs.miden.co/cards/miden-managed-authorizations/card-management/blacklist-merchant.md): Description Blocks a specific merchant from processing transactions on a card using the merchant’s Merchant ID (MID) . This endpoint allows you to restrict a card from being used at one or more specific merchants by adding the merchant’s MID to the card’s blacklist configuration . Once a merchant is blacklisted, any transaction attempted with that MID on the specified card will be declined. This is a card-level merchant restriction control used to enforce transaction-level blocking rules.
  • [Remove Merchant Blacklist](https://docs.miden.co/cards/miden-managed-authorizations/card-management/remove-merchant-blacklist.md): Description Removes a previously blocked merchant from a card’s blacklist using the merchant’s Merchant ID (MID) . This endpoint allows you to permanently remove a merchant restriction from a specific card. Once removed, the card will be able to process transactions with that merchant without any restrictions. This is a permanent merchant unblocking operation and updates the card’s blacklist configuration.
  • [Remove Merchant Blacklist One-time](https://docs.miden.co/cards/miden-managed-authorizations/card-management/remove-merchant-blacklist-one-time.md): Description Temporarily removes a merchant from a card’s blacklist to allow a single transaction using the merchant’s Merchant ID (MID) . This endpoint allows a previously blocked merchant to be used for one-time authorization on a specific card. After the transaction is completed (whether successful or declined), the merchant is automatically re-applied to the blacklist , ensuring that the restriction remains in place for future transactions. This is a temporary merchant override operation and does not permanently remove the merchant from the blacklist. Usage Use this endpoint when you need to: allow a one-time transaction with a previously blocked merchant retry a failed transaction that was blocked due to merchant restrictions process exception-based approvals without removing restrictions permanently honor a specific transaction request while maintaining overall merchant controls This is a temporary merchant unblocking (one-time override) operation. Notes This endpoint allows only one transaction with the specified merchant MID. After the transaction attempt (successful or not), the merchant is automatically re-blocked . This does not remove the MID permanently from the blacklist. The MID must already exist in the card’s blacklist configuration for this operation to be valid. If the merchant is not blacklisted, the request may fail. This operation does not modify other merchant restrictions on the card. The temporary unblock applies only to the next transaction attempt with that MID. Subsequent transactions with the same MID will be declined unless this endpoint is called again.
  • [Whitelist Merchant](https://docs.miden.co/cards/miden-managed-authorizations/card-management/whitelist-merchant.md): Description Allows a card to be used only with specific merchants by adding merchant(s) to the card’s whitelist using their Merchant ID (MID) . When a whitelist is applied, the card will only approve transactions from the specified merchant MID(s) . All other merchants not included in the whitelist will be declined. This is a restrictive merchant control operation that enforces strict merchant-level transaction rules on the card.
  • [Remove Merchant Whitelist](https://docs.miden.co/cards/miden-managed-authorizations/card-management/remove-merchant-whitelist.md): Description Removes one or more merchants from a card’s whitelist using the merchant’s Merchant ID (MID) . This endpoint allows you to revoke previously granted merchant access for a specific card. Once removed, the card will no longer be restricted to those merchants and will follow the default card controls or any other configured restrictions (e.g., blacklist rules). This is a permanent whitelist removal operation and updates the card’s merchant whitelist configuration.
  • [Set Card PIN](https://docs.miden.co/cards/miden-managed-authorizations/card-management/set-card-pin.md): Description Sets the transaction PIN for a card. Currently, this functionality is supported only for NGN cards . This endpoint allows you to assign a PIN (Personal Identification Number) to a card, which is required for PIN-based transactions such as online transactions. Setting the PIN is a critical step in card activation and should be performed immediately after card issuance to enable full card usage.
• [Authorization](https://docs.miden.co/cards/customer-managed-authorizations/authorization.md): Supported Authorization Decision Codes The following response combinations are supported when returning an authorization decision to Miden. Merchants should return the responseCode , responseReasonCode , and responseMessage combination that most accurately represents the authorization outcome. Then use this table: Response Code Response Reason Code Response Message `000` `APPROVE` Transaction approved `911` `ERROR` An unexpected error occurred `111` `INVALID_AMT` Invalid transaction amount `112` `CRD_INVALID` Invalid card identifier `113` `INVALID_REQ` Invalid unique key `114` `LIMIT_EXCEED` Maximum top-up limit exceeded `115` `INVALID_REQ` Organization is disabled or KYC has not been approved `116` `INSUFF_FUNDS` Insufficient funds `117` `CRD_INACT` Card is not active `119` `TXN_NOT_PERMIT` Transaction is not permitted `121` `RESTRICTED` Currency is not supported `122` `INVALID_PIN` Invalid card PIN `123` `INVALID_REQ` Invalid cardholder name `124` `INVALID_EXPIRY` Invalid card expiry date `125` `BLK_MRCH` Merchant is not allowed `126` `RESTRICTED` Country is not supported `127` `RESTRICT_MCC` Merchant category is not supported `128` `SUSPECT_FRAUD` Transaction declined due to suspicious activity `129` `LIMIT_EXCEED` Transaction limit exceeded `130` `VELOCITY_EXCEED` Transaction velocity limit exceeded `131` `INVALID_REQ` Invalid request `132` `INVALID_DATE` Invalid request date `133` `INVALID_TXN` Invalid transaction `134` `INVALID_MERCHANT` Invalid merchant `135` `INVALID_ACC` Invalid account `136` `FORMAT_ERR` Invalid request format `137` `SEC_ERROR` Security validation failed `138` `DUP_TXN` Duplicate transaction `139` `DUP_REQ` Duplicate request `140` `DO_NOT_HONOUR` Do not honour `141` `RESTRICTED` Card is restricted `142` `EXPIRED` Card has expired `143` `CRD_CLOSED` Card is closed `144` `CRD_LOST` Card has been reported lost or stolen `145` `FRAUD_TXN` Fraudulent transaction `146` `AUTH_FAILED` Authentication failed `147` `PIN_EXCEED` Maximum PIN attempts exceeded `148` `NO_CARD` Card record not found `149` `UNAUTHORIZED` Unauthorized transaction `150` `SYS_MALFUNCTION` System malfunction `151` `SYS_TIMEOUT` System timeout `152` `TERMPROC_ER` Terminal processor error `153` `NO_CASH_SERVICE` Cash service is not available `154` `LAW_VIOLATION` Transaction declined due to legal restrictions `155` `TXN_NON_AML` Transaction does not meet AML requirements `156` `FILE_TEMP_UNAVLB` Required file is temporarily unavailable `157` `UNABLE_TO_LOCATE` Unable to locate the requested record `158` `INFO_MISSING` Required information is missing `159` `DUP_TRANSMISSION` Duplicate transmission `160` `STOP_PAY_ORDER` Stop payment order `161` `NEG_BAL_EXC_LIMT` Negative balance exceeds the permitted limit `162` `INVALID_TRACK` Invalid card track data `163` `INVALID_EMVDATA` Invalid EMV data `164` `INV_PARAUTH_AMT` Invalid partial authorization amount `165` `TXN_EXC_PREAUTH` Transaction amount exceeds the preauthorization amount `166` `RE_ENTER_TXN` Please re-enter the transaction `167` `REFER_ISSUER` Refer to card issuer `168` `REFER_ISSUER_SP` Refer to card issuer - special condition `169` `NO_ISSUER` Card issuer could not be identified `170` `NO_ACTION` No action taken `171` `NO_FIN_IMPACT` Transaction has no financial impact `172` `NO_STIP_TIMEOUT` Issuer or switch unavailable or timed out `173` `REC_INST_INVALID` Financial institution could not be found `174` `UNSOLICITED_REV` Unsolicited reversal `175` `ALREADY_REV` Transaction has already been reversed `176` `AUTH_DECLINE` Authorization declined `177` `ERROR` Authorization error `178` `REQ_ERROR` Request error `179` `NO_DECLINE_REAS` No reason to decline `180` `EKYC_FAIL` Verification failed `181` `OFAC_FAIL` OFAC screening failed `182` `EKYC_FAIL` KYC verification failed `183` `EKYC_FAIL_MAN_Q` KYC manual review is required `184` `ADDRESS_INVALID` Address verification failed `185` `ID_INVALID` Identity verification failed `186` `CRD_ACC_BLACKM` Merchant is blacklisted `187` `CRD_ACC_VERIFY` Card account verification failed `188` `CRD_ACC_TRANS` Valid CVV verification was not received `189` `VELOCITY_EXCEED` Transaction frequency limit exceeded `201` `WR_PIN` Incorrect PIN `202` `INVALID_PIN` Invalid PIN `203` `NO_PIN_ASSIGNED` No PIN assigned to card `204` `PIN_ALREADY_PRES` PIN already exists `205` `NO_PIN_CARD` PIN operation is not supported for this card `206` `PIN_CONFIRM_FAIL` PIN confirmation failed `207` `NOT_EFFECTIVE` Card is not yet effective `208` `RESTRICTED_PICK` Restricted card - retain card `209` `SPECIAL_PICK` Special condition - retain card `210` `STOLEN_PICK` Stolen card - retain card `211` `FRAUDULENT_PICK` Fraudulent use suspected - retain card `212` `LOST_PICK` Lost card - retain card `213` `AQU_SEC` Contact acquirer security `214` `AQU_SEC_PICK` Contact acquirer security and retain card `215` `CLOSED_PICK` Closed card - retain card `216` `SUSPECT_FRAUD` Transaction declined due to suspected fraud `217` `INSUFFICIENT` Invalid amount or insufficient funds `218` `CH_CANCEL` Transaction cancelled by cardholder `219` `ISS_CANCEL` Transaction cancelled by issuer `220` `CH_DEAD` Cardholder deceased `221` `ACC_CLOSED` Account is closed `222` `ACC_FROZEN` Account is frozen `223` `ACC_NOTAVLBL` Account is not available `224` `ACC_UNQUALIF` Account is not qualified for this transaction `225` `RECV_UNQUALI` Receiving institution is not qualified `226` `RECV_REJECT` Transaction refused by receiving institution `227` `ORIG_REQ` Transaction returned at originator's request `228` `AUTH_REVOKED` Authorization has been revoked `229` `CREDIT_ISSUED` Credit was previously issued `230` `CREDIT_NOT_PROC` Credit was not processed `231` `WARN_BULLETIN` Card appears on warning bulletin `232` `NO_AUTH` Required authorization was not obtained `233` `TXN_NOT_RECON` Transaction was not reconciled `234` `ACC_NOT_FILE` Account number not found `235` `TXN_AMT_DIFF` Transaction amount differs from expected amount `236` `NO_CH_AUTH` Cardholder authorization was not obtained `237` `FRAUD_TXN` Fraudulent processing detected `238` `CH_DENIES` Cardholder denies the transaction `239` `DUPLICATE` Duplicate transaction processing `301` `FV_W_ML` Transaction flagged by fraud detection rules `302` `SUSPECT_FRAUD` Behavioural risk detected `303` `SEC_ERROR` Device risk detected `304` `RESTRICTED` Geographic risk detected `305` `OFAC_FAIL` Sanctions screening failed `306` `IND_RISK` PEP match detected `307` `TXN_NON_AML` AML risk detected `308` `CRD_ACC_BLACKM` High-risk merchant detected `309` `RESTRICTED` High-risk country detected `310` `INVALID_REQ` Transaction restricted by card program Notes 000 / APPROVED is the successful authorization response. For declined or unsuccessful transactions, return the supported response combination that most accurately describes the reason. The merchant should not invent custom responseReasonCode values outside the supported list unless Miden explicitly confirms that custom codes are supported. The decision must be returned within the agreed response time. If a valid response is not received within the agreed response time, Miden applies the configured Default Authorization Decision. The transaction decision is returned by Miden to the card network or switch; it is not sent directly by the merchant to the cardholder or card network.
  • [Authorization Callback](https://docs.miden.co/cards/customer-managed-authorizations/authorization/authorization-callback.md): Description Miden sends an HTTP POST request to the merchant’s configured Authorization URL whenever a supported card transaction event requires processing under the Customer-Managed Authorization model. The merchant must evaluate the request and return an approval or decline decision within the agreed response time. The callback contains transaction, merchant, authorization, settlement, and charge information that can be used when processing the transaction. Usage Implement this endpoint in your system and configure its publicly accessible URL in: Miden Portal → Settings → Developer → Card Transaction Authorizations Your endpoint must: Accept HTTP POST requests. Accept JSON. Return HTTP 200 OK . Return a valid authorization response body. Respond within the agreed response time. Charge Types The chargeType field identifies the type of charge contained in the charge field. Charge Type When Applied Description ContactlessCharge Authorization Charge associated with a contactless card transaction. This charge is provided during the authorization event. CrossBorderCharge Settlement Charge associated with a cross-border transaction. This charge is provided during settlement. Contactless Charge When a charge applies to a contactless transaction, Miden provides the charge during the authorization request. Example: { "requestType": "Authorization", "charge": 1.50, "chargeType": "ContactlessCharge", "isContactlessPayment": true } isContactlessPayment indicates that the transaction was performed using contactless payment, while chargeType identifies the applicable charge. Cross-Border Charge Cross-border charges are provided during the settlement stage rather than during the initial authorization. Example: { "requestType": "Settlement", "charge": 2.75, "chargeType": "CrossBorderCharge" } You should therefore not expect a cross-border charge to necessarily be available during the initial authorization request. Amount and Currency Interpretation For Customer-Managed Authorization, the transaction amounts should be interpreted as follows: Field Meaning transactionAmount USD equivalent of the transaction amount. authorizationAmount Amount being authorized in the transaction currency. transactionCurrencyCode Currency applicable to the authorizationAmount . settlementAmount Amount associated with settlement, where applicable. settlementCurrencyCode Currency applicable to the settlement amount. For example: { "transactionAmount": 3.75, "authorizationAmount": 19000, "transactionCurrencyCode": "BRL" } This represents: transactionAmount : USD 3.75 authorizationAmount : BRL 19,000 transactionCurrencyCode : BRL charge should be interpreted together with chargeType . ContactlessCharge is provided during authorization where applicable. CrossBorderCharge is provided during settlement where applicable. isContactlessPayment indicates the payment method and should not be interpreted as the charge itself. transactionAmount is always expressed in USD. authorizationAmount represents the amount in the currency identified by transactionCurrencyCode . You must return a valid authorization response within the agreed response time. The Authorization Callback uses the same HMAC verification scheme used for Miden webhook verification. Endpoint This endpoint is hosted by you. Example: POST https://api.yourcompany.com/cards/authorizations Notes The merchant must return HTTP 200 OK for a valid authorization response. . HTTP 200 OK does not automatically approve the transaction. responseCode = "000" approves the transaction. A supported non- 000 responseCode declines the transaction. The merchant must respond within the agreed response time. The current integration guide specifies a response period of 400 milliseconds. Where no valid response is received within the agreed response time, Miden applies the configured Default Authorization Decision. The merchant should use eventId , reference , and other supplied transaction identifiers to prevent duplicate processing. The merchant should validate the request before applying balance or transaction updates. The transaction decision is returned to Miden, not directly to the card network or switch. Webhook events should be processed separately from the real-time authorization response. The endpoint should not expose sensitive internal error details in responseMessage . Once configured, your system can participate directly in card transaction authorization decisions while Miden continues to manage transaction processing and network connectivity.
• [Manage Card Limit](https://docs.miden.co/cards/customer-managed-authorizations/card-management/manage-card-limit.md): Description This endpoint allows you to configure or update the spending and funding limits applied to a specific card. The limits control the maximum amount permitted for a single transaction and the cumulative amount the card can spend daily or monthly. The endpoint also accepts a lifetimeLimit , which represents the card balance used when making transaction-funding decisions. Usage Use this endpoint to update the controls applied to a card under the Customer-Managed Cards model. Replace {cardId} with the unique identifier of the card whose limits you want to update. Note : lifetimeLimit represents the card balance—available funds after considering all authorizations performed by the card—that will be used for transaction-funding decisions. Notes All limit values must be supplied in the currency associated with the card. transactionLimit applies to each individual transaction. dailyLimit applies to the cumulative amount spent within a day. monthlyLimit applies to the cumulative amount spent within a month. lifetimeLimit represents the card balance—available funds after considering all authorizations performed by the card—that will be used for transaction-funding decisions. The specified cardId must belong to an existing card associated with your organization. Limit updates apply to subsequent card authorization decisions. The response returns the card’s current limit information under data.cardLimits . The sample response values under data.cardLimits differ from the values in the sample request. Confirm whether the response returns the newly submitted values or the card’s previously stored limits before publishing the final production example. Fields that do not apply to the card or operation may return null or 0 .
• [Activate/Deactivate Cards](https://docs.miden.co/cards/customer-managed-authorizations/card-management/activate-deactivate-cards.md): Description Activates or deactivates a card by toggling its current usage status. This endpoint is used to freeze or unfreeze a card without terminating it. Deactivating a card temporarily prevents it from being used for transactions, while activating it restores the card for normal use. This operation is useful for temporary card control, fraud prevention, security response, or operational card management. Usage Use this endpoint when you need to: temporarily disable a card to prevent further usage re-enable a previously suspended card freeze a card that is suspected to be compromised unfreeze a card after review or customer confirmation This is a card status management operation. Notes Set activated to false to deactivate or freeze the card. Set activated to true to activate or unfreeze the card. Deactivating a card does not terminate it; it only changes its usage status. The response data object reflects the updated state of the card after the operation. The status field shows the effective result of the request, such as Card - Suspended or Card - Active . No funds are moved and no balance adjustment is performed during this operation. Card limits remain unchanged by this request.
• [Terminate Cards](https://docs.miden.co/cards/customer-managed-authorizations/card-management/terminate-card-copy.md): Description Terminates a card permanently and prevents it from being used for any future transactions. This endpoint is used to permanently deactivate a card and close its active lifecycle. Once terminated, the card cannot be reactivated for use. The operation returns the updated card state, including its termination timestamp, final available balance, and related card metadata. This is a permanent card lifecycle action and should be used only when the card is no longer needed or must be permanently retired. Usage Use this endpoint when you need to: permanently stop a card from being used close a card that should no longer remain active retire a card after operational, compliance, or security review ensure a terminated card cannot be reactivated for future spending This is a card termination operation. Notes This endpoint permanently terminates the specified card. A terminated card cannot be used for future transactions. The response data object reflects the final state of the card after termination. terminateDate is populated only when the termination is successful. In the sample success response, availableBalance becomes 0.0 after termination, while balanceBeforeTermination shows the balance that existed before the operation was completed. If the card has already been terminated, the request fails and returns data as null . The status field in the success response reflects the post-termination card state.
• [Wallets (Positions)](https://docs.miden.co/cards/wallets-positions.md): Overview The Wallets module provides merchants with a structured way to hold, organize, and manage funds. Every merchant is provisioned with one or more Parent Wallets , each representing a specific currency (for example, USD or NGN). Parent Wallets operate independently, maintaining their own balances, transaction history, and financial activity. A Parent Wallet can also contain one or more Subwallets , which are used to allocate funds for specific business purposes such as settlements, refunds, marketing, payroll, or collections. Subwallets always belong to a single Parent Wallet and cannot exist independently. The total balance displayed for a Parent Wallet includes its own balance together with the balances of all Subwallets under it, while each Subwallet maintains its own spendable balance. This section documents the APIs for managing Parent Wallets and Subwallets, viewing balances and transaction history, transferring funds, retrieving statements, and performing currency-related operations.
  • [Parent Wallet](https://docs.miden.co/cards/wallets-positions/parent-wallet.md): Overview A Parent Wallet is the primary wallet for a specific currency within a merchant account. Each Parent Wallet operates independently, maintaining its own balance, transaction history, and financial activity. When a merchant is onboarded, Parent Wallets are automatically created for supported currencies (for example, USD and the merchant's local currency). Depending on the merchant's configuration, additional Parent Wallets may also be created. A Parent Wallet can be used directly for funding transactions, receiving credits, making payouts, and performing other supported wallet operations. It can also contain one or more Subwallets used to organize funds for different business functions. The total balance displayed for a Parent Wallet includes both its own balance and the balances of all Subwallets under it, while each Subwallet retains its own independent spendable balance. This section contains APIs for viewing Parent Wallet balances, transaction history, statements, currency exchange operations, and transferring funds between Parent Wallets, Subwallets, and external accounts.
    • [Initiate Currency Swap](https://docs.miden.co/cards/wallets-positions/parent-wallet/initiate-currency-swap.md): Description Initiates a currency swap from a source wallet currency to USD. This endpoint locks in an exchange rate and returns a swap reference along with the conversion details. The swap must be completed within the provided expiration window, otherwise it becomes invalid. Usage Use this endpoint when you need to: initiate a currency conversion from a local currency to USD lock in an exchange rate before executing a swap retrieve conversion amounts and applicable rates prepare for completing a swap transaction This is a currency swap initiation operation . Notes The swap is time-bound and must be completed before expiration. Exchange rates are locked at the time of initiation. A new swap must be initiated if the previous one expires. targetCurrency is always USD for this operation. The returned swapReference is required to complete the swap.
    • [Complete Currency Swap](https://docs.miden.co/cards/wallets-positions/parent-wallet/complete-currency-swap.md): Description Finalizes a previously initiated currency swap. This endpoint completes the conversion by debiting the source wallet and crediting the target wallet using the locked rate obtained during initiation. The swap must be completed within its validity window. Usage Use this endpoint when you need to: complete a previously initiated currency swap apply the locked exchange rate to wallet balances finalize conversion from local currency to USD update wallet balances after swap confirmation This is a currency swap completion operation . Notes The swap must be completed within the expiration window from initiation. Exchange rate used is the one locked during initiation. A swap cannot be completed more than once. If the swap expires, a new swap must be initiated. This operation performs the actual wallet balance update.
    • [Wallets Balance](https://docs.miden.co/cards/wallets-positions/parent-wallet/wallets-balance.md): Description Retrieves the current balances for one or more wallets associated with a merchant. This endpoint provides a consolidated view of wallet positions across currencies, including total balance, available balance, and any restricted or reserved amounts. It enables real-time visibility into funds available for operations such as card transactions, settlements, and currency swaps. Usage Use this endpoint when you need to: view current wallet balances across currencies check available funds before initiating transactions monitor reserved or restricted amounts (e.g., liens, holds) retrieve wallet-specific balance information This is a wallet balance retrieval operation . Notes walletAvailableBalance represents the actual spendable amount. walletBalance includes both available and restricted funds. When a card goes into a negative balance, an equivalent amount is reserved from the wallet and reflected in walletReservedBalance . Reserved funds are automatically released back to the available balance when the negative position is cleared (e.g., card funding or regularization). walletUnclearBalance represents funds that are pending settlement. lienAmount represents funds restricted due to external obligations.
    • [Running Balance](https://docs.miden.co/cards/wallets-positions/parent-wallet/running-balance.md): Description Retrieves a wallet statement for a specified wallet within a defined date range. This endpoint returns the transaction entries that make up the wallet statement for the selected period, including debit and credit activity, narrations, references, and running balance. Usage Use this endpoint when you need to: generate a wallet statement for a specific period review wallet activity within a date range support reconciliation, reporting, and auditing track debits, credits, and running balances for a wallet This is a wallet statement retrieval operation . Notes walletNumber , startDate , and endDate are required for this endpoint. The statement is returned as a list of transaction entries within the specified period. formattedAmount reflects the signed transaction value for statement presentation. runningBalance shows the wallet balance after each transaction entry. Both internal and third-party references may be returned for traceability. Transactions may include debit and credit entries depending on wallet activity.
    • [Wallet Transactions](https://docs.miden.co/cards/wallets-positions/parent-wallet/wallet-transactions.md): Description Retrieves wallet transaction history for a merchant. This endpoint provides a paginated list of transactions across wallets, including details such as transaction amount, type, narration, references, and running balance at the time of each transaction. Usage Use this endpoint when you need to: retrieve wallet transaction history filter transactions by date, wallet, or reference track financial activity across wallets support reconciliation and auditing This is a wallet transaction retrieval operation . Notes If no filters are provided, all transactions are returned in a paginated format. Transactions may include debits and credits across different wallet currencies. runningBalance reflects the wallet balance at the time of the transaction. Pagination parameters determine the subset of results returned. Transaction references can be used for reconciliation and traceability.
    • [Wallet Statement](https://docs.miden.co/cards/wallets-positions/parent-wallet/wallet-statement.md): Description Retrieves a wallet statement for a specified wallet within a defined date range. This endpoint returns the transaction entries that make up the wallet statement for the selected period, including debit and credit activity, narrations, references, and running balance. Usage Use this endpoint when you need to: generate a wallet statement for a specific period review wallet activity within a date range support reconciliation, reporting, and auditing track debits, credits, and running balances for a wallet This is a wallet statement retrieval operation . Notes walletNumber , startDate , and endDate are required for this endpoint. The statement is returned as a list of transaction entries within the specified period. formattedAmount reflects the signed transaction value for statement presentation. runningBalance shows the wallet balance after each transaction entry. Both internal and third-party references may be returned for traceability. Transactions may include debit and credit entries depending on wallet activity.
    • [Get Rate](https://docs.miden.co/cards/wallets-positions/parent-wallet/get-rate.md): Description Retrieves the applicable exchange rate for a currency swap between a specified source currency and USD. This endpoint provides the current buy and sell rates used for wallet currency conversion. The returned rate is time-bound and valid for a short duration, ensuring consistency during swap operations. Usage Use this endpoint when you need to: fetch the current exchange rate before initiating a currency swap determine conversion cost between local currency and USD validate pricing for FX operations ensure rate consistency prior to executing a swap This is a currency rate retrieval operation . Notes The rate returned is typically valid for a short duration (e.g., ~2 minutes). Always fetch a fresh rate before initiating a currency swap. buyRate and sellRate may differ due to spread. Only supported currencies can be queried. The destination currency is always USD for this endpoint.
  • [Sub-Wallets](https://docs.miden.co/cards/wallets-positions/sub-wallet.md): Overview A Subwallet is a wallet created under a Parent Wallet to organize and manage funds for a specific business purpose. Unlike Parent Wallets, Subwallets cannot exist independently and always belong to a single Parent Wallet. Subwallets maintain their own balances and can be used to separate funds for different operational activities such as settlements, refunds, marketing, payroll, or collections. Funds allocated to a Subwallet are available only within that Subwallet and do not grant access to the Parent Wallet's own balance. A Parent Wallet can contain multiple Subwallets, making it easier to segregate funds while maintaining a consolidated view of balances at the Parent Wallet level. This section contains APIs for creating and managing Subwallets, allocating funds, retrieving balances, viewing transaction history, and transferring funds between Subwallets, Parent Wallets, and external accounts.
    • [Create Subwallet](https://docs.miden.co/cards/wallets-positions/sub-wallet/create-subwallet.md): Description Creates a new Subwallet under an existing Parent Wallet. Subwallets are used to organize and manage funds for a specific operational purpose while remaining tied to their Parent Wallet. Each Subwallet maintains its own balance and can only use funds available within that Subwallet. The Parent Wallet must support Subwallet creation. USD Parent Wallets do not support Subwallets by design. Usage Use this endpoint to: Create a Subwallet under an eligible Parent Wallet. Separate funds for specific business purposes such as savings, settlements, refunds, payroll, marketing, collections, or other operational use cases. Assign a unique code and name to a Subwallet for identification. Optionally create the Subwallet with an initial balance. Notes A Subwallet must always be created under a valid Parent Wallet. USD Parent Wallets do not support Subwallets by design. The Subwallet operates in the currency associated with its Parent Wallet. subWalletName should be unique within the Parent Wallet. Store the returned subWalletId ; it is required for subsequent Subwallet operations. A Subwallet can only spend or use funds available in its own balance. It cannot draw directly from the Parent Wallet's own balance. The Parent Wallet's total displayed balance includes its own balance plus the balances of all Subwallets under it. Use initialBalance: 0 where the Subwallet should be created without an initial allocation.
    • [Create Subwallet with VA](https://docs.miden.co/cards/wallets-positions/sub-wallet/create-subwallet-with-va.md): Description Creates a new Subwallet under an eligible Parent Wallet and automatically provisions a virtual account for the Subwallet. The virtual account can be used to receive funds directly into the Subwallet. Once funds are received, the Subwallet balance is updated and the amount also contributes to the total balance reflected on the Parent Wallet. This endpoint is intended for NGN Subwallets where a dedicated virtual account is required. Usage Use this endpoint when you need to: Create a new Subwallet under an existing Parent Wallet. Provision a dedicated virtual account for the Subwallet at creation. Receive external NGN inflows directly into a specific Subwallet. Separate collections or incoming funds by customer, department, product, project, or other business purpose. Notes The Parent Wallet identified by clientWalletId must support Subwallet creation. This endpoint creates both the Subwallet and its associated virtual account in a single request. Funds sent to the returned thirdPartyWalletNumber are credited to the associated Subwallet. The Subwallet can only spend or use funds available in its own balance. The Parent Wallet's total balance reflects its own balance plus the balances of all Subwallets under it. Store the returned subWalletId and thirdPartyWalletNumber for subsequent Subwallet and collection operations. subWalletCode and subWalletName should be unique within the Parent Wallet. dob must be supplied in YYYY-MM-DD format. Based on the sample provided, either the individual name fields ( firstname , lastName ) or the Name field may be used depending on the virtual-account ownership type.
    • [Attach VA to Subwallet](https://docs.miden.co/cards/wallets-positions/sub-wallet/attach-va-to-subwallet.md): Description Attaches a virtual account to an existing Subwallet. Use this endpoint when a Subwallet has already been created without a virtual account and you want to provision a dedicated account number that can receive external inflows directly into that Subwallet. The request collects the identification and contact information required for virtual account provisioning. Usage Use this endpoint to: Attach a virtual account to an existing Subwallet. Enable direct external funding into a Subwallet. Provision a virtual account after the Subwallet has already been created. Collect the account-holder information required for virtual account creation. Notes The Subwallet must already exist before a virtual account can be attached to it. The supplied BVN and personal details should belong to the individual being used for virtual account provisioning. dob must be provided in YYYY-MM-DD format. Once attached, the virtual account can be used to receive external inflows directly into the associated Subwallet. Funds received through the virtual account are credited to the Subwallet and contribute to the total balance reflected on its Parent Wallet. Treat BVN and other personally identifiable information as sensitive data and avoid exposing them in logs. The response you provided currently echoes the request fields and does not include the provisioned virtual account number or bank name. If the production response returns those fields, they should be added to this documentation.
    • [SubWallet Bank Transfer](https://docs.miden.co/cards/wallets-positions/sub-wallet/subwallet-bank-transfer.md): Description Initiates an NGN bank transfer directly from a Subwallet to a beneficiary bank account. The transfer amount is debited from the specified Subwallet balance. The Subwallet must have sufficient available funds to cover the transaction amount and any applicable charges. Usage Use this endpoint to: Send funds from a specific Subwallet to an external bank account. Process payouts directly from an operational Subwallet. Keep outgoing payments separated by department, branch, customer, project, or other business purpose. Reconcile external transfers against a specific Subwallet.
    • [Move Funds between sub wallets](https://docs.miden.co/cards/wallets-positions/sub-wallet/move-funds-between-sub-wallets.md): Description Transfers funds from one Subwallet to another Subwallet under the same Parent Wallet. The specified amount is debited from the source (debit) Subwallet and credited to the destination (credit) Subwallet. This operation allows merchants to redistribute funds between operational Subwallets without affecting the Parent Wallet's own balance. Usage Use this endpoint to: Move funds between Subwallets under the same Parent Wallet. Reallocate operational budgets between departments or business units. Transfer funds between project, branch, or customer-specific Subwallets. Correct or rebalance allocated funds across Subwallets.
    • [Allocate from main wallet to sub wallet](https://docs.miden.co/cards/wallets-positions/sub-wallet/allocate-from-main-wallet-to-sub-wallet.md): Description Allocates funds from a Parent Wallet to a Subwallet under the same wallet hierarchy. The specified amount is transferred from the Parent Wallet's own balance and credited to the selected Subwallet. This enables merchants to distribute funds across operational Subwallets while maintaining centralized control through the Parent Wallet. Usage Use this endpoint to: Allocate funds from a Parent Wallet to a Subwallet. Fund newly created Subwallets. Distribute operational budgets across departments, branches, projects, or business units. Increase the available balance of a specific Subwallet.
    • [Allocate from sub wallet to main wallet](https://docs.miden.co/cards/wallets-positions/sub-wallet/allocate-from-sub-wallet-to-main-wallet.md): Description Moves funds from a Subwallet back to its Parent Wallet. The specified amount is debited from the Subwallet's available balance and returned to the Parent Wallet's own balance. This operation is useful when previously allocated funds need to be reclaimed, consolidated, or reassigned. Usage Use this endpoint to: Return unused funds from a Subwallet to its Parent Wallet. Reclaim operational allocations. Consolidate balances back into the Parent Wallet. Prepare funds for reallocation to another Subwallet or other supported wallet operation.
    • [Get SubWallets Transactions](https://docs.miden.co/cards/wallets-positions/sub-wallet/get-subwallets-transactions.md): Description Retrieves the transaction history for a specific Subwallet. The response includes credits, debits, internal transfers, allocations between the Parent Wallet and Subwallet, balance movements, transaction status, and pagination details. Usage Use this endpoint to: Retrieve the transaction history of a Subwallet. Reconcile credits and debits. Track allocations from the Parent Wallet. Track transfers back to the Parent Wallet. Review transfers between Subwallets.
    • [Get SubWallets](https://docs.miden.co/cards/wallets-positions/sub-wallet/get-subwallets.md): Description Retrieves Subwallets associated with the merchant. The endpoint can be used to return all Subwallets or retrieve a specific Subwallet when a subWalletId is provided. The response includes Subwallet identification details, virtual account information, balances, status, and pagination metadata. Usage Use this endpoint to: Retrieve all Subwallets available to the merchant. Retrieve details of a specific Subwallet. View current available, reserved, and uncleared balances. Retrieve the virtual account details attached to a Subwallet. Check whether a Subwallet is active or closed.
    • [Get SubWallets Download](https://docs.miden.co/cards/wallets-positions/sub-wallet/get-subwallets-download.md): Description Retrieves all Subwallets associated with the merchant in a downloadable format. The response contains the complete list of Subwallets together with their balances, virtual account details, and status information, making it suitable for reporting, reconciliation, and offline analysis. Usage Use this endpoint to: Download a complete list of Subwallets. Export Subwallet information for reconciliation and reporting. Review balances and virtual account details across all Subwallets. Maintain offline records of merchant Subwallets. Support operational and financial audits.
    • [Get SubWallets Transactions Download](https://docs.miden.co/cards/wallets-positions/sub-wallet/get-subwallets-transactions-download.md): Description Retrieves the complete transaction history for a specified Subwallet in a downloadable format. The response includes all recorded transactions for the Subwallet, including allocations, internal transfers, adjustments, credits, debits, and balance movements. This endpoint is intended for reporting, reconciliation, auditing, and offline record keeping. Usage Use this endpoint to: Download the complete transaction history of a Subwallet. Reconcile Subwallet credits and debits. Export transactions for reporting or auditing. Review balance movements and transaction status. Maintain offline records of Subwallet activity.
• [Collect](https://docs.miden.co/payment-gateway/collect.md): These APIs enable you to accept and manage payments from customers using Miden's supported collection methods. Use these APIs to create payment experiences for one-time or reusable collections, generate virtual accounts for receiving bank transfers, and retrieve the information required to track collections initiated through your integration. This section includes APIs for: Creating and managing Payment Links Creating and managing Virtual Accounts Retrieving collection-related resources and transaction information Use the appropriate collection method based on how you want customers to pay and the payment experience you want to provide.
  • [Single-Use Link](https://docs.miden.co/payment-gateway/collect/create-payment-links/single-use-link.md): Description Creates a hosted payment page for a single transaction and returns a shareable checkout URL. The generated link can be sent directly to a customer, who can then open the hosted page and complete payment using the channels available for that transaction configuration. A single-use payment link can only be used for one successful payment. Once a payment is completed successfully, the link becomes inactive and cannot be reused for subsequent transactions. Usage Use this endpoint when you need to: Create a payment link for a customer to checkout in both NGN and USD. Collect payments without building a direct checkout UI. Share a hosted checkout page through email, chat, SMS, or social platforms. Send customers a payment retry option for incomplete transactions. Generate a one-time payment link that becomes unusable after a successful payment. This is a payment link creation operation intended for single-use payment links. If you need a payment link that can accept multiple successful payments, use the Multiple-Use Payment Link option instead. Notes Use a unique merchantReference for each payment link to make reconciliation easier. The amount should be sent in minor units based on the currency format supported by your integration. The returned launchUrl can be distributed through any customer-facing channel. Available payment options on the hosted checkout page may vary based on the transaction setup. Payment links may also be created automatically by other flows in the system, such as invoice payment actions. Redirect URL = Postback url
  • [Multiple-Use Link](https://docs.miden.co/payment-gateway/collect/create-payment-links/single-use-link-copy.md): Description This endpoint allows you to create a payment link that can be used successfully more than once. Unlike a single-use payment link, a multiple-use payment link remains active until it reaches its configured usage limit, passes its expiry date, or is manually deactivated. Usage Use this option when the same payment link needs to accept payments from multiple customers or support repeated payments. To create a multiple-use payment link: Set type to Multiple . Provide a valid usageLimit of at least 1 . Optionally provide an expiryDate . The payment link will stop accepting payments when the configured usage limit is reached, even if the expiry date has not passed. Where an expiry date is provided, the link will stop accepting payments after that date, regardless of the number of successful transactions completed. Notes usageLimit is required when type is set to Multiple . usageLimit must be an integer greater than or equal to 1 . Only successful payment transactions count towards the configured usage limit. The payment link is automatically deactivated once the number of successful transactions reaches usageLimit . expiryDate is optional. Where expiryDate is provided, the link stops accepting payments after the specified date, even if the usage limit has not been reached. Where both usageLimit and expiryDate are provided, the link becomes inactive when either condition is reached first. Unsuccessful, failed, or abandoned payment attempts should not count towards the usage limit. The payment link may also be manually deactivated before reaching its usage limit or expiry date. A checkout preset configuration can be created and saved from the merchant’s settings. Where isDefault is set to true , the configuration is marked as the merchant’s default checkout preset. When presetConfigId is provided during payment link creation, the system retrieves and applies the values saved against that configuration. In this case, amount and currency are not required. Where presetConfigId is omitted, amount and currency must be provided. Values from the preset configuration take precedence over corresponding values supplied directly in the payment link request.
  • [Generate Dynamic Virtual Account](https://docs.miden.co/payment-gateway/collect/virtual-accounts/generate-dynamic-virtual-account.md): Description Creates a dynamic virtual account that can be used to receive a bank transfer for a checkout transaction. This endpoint generates a temporary account number tied to the customer details provided, allowing the customer to complete payment through bank transfer into a dedicated virtual account. Usage Use this endpoint when you need to: generate a virtual account for a customer payment receive checkout payments through bank transfer assign a temporary account number to a single payment flow support account-based payment collection without card entry This is a dynamic virtual account creation operation . Notes This endpoint generates a dynamic virtual account for payment collection. The returned account details should be presented to the customer exactly as received. Customers complete payment by transferring funds to the generated account number. Account creation may depend on successful BVN validation and provider availability. A dynamic virtual account is typically tied to a specific checkout or payment flow.
  • [Get All Virtual Accounts](https://docs.miden.co/payment-gateway/collect/virtual-accounts/get-all-virtual-accounts.md): Description Retrieves a paginated list of virtual accounts created for the merchant. This endpoint returns both dynamic and static virtual accounts together with account identity, status, currency, collection activity, and metadata needed for monitoring and reconciliation. The response includes optional filters for date range and specific account number lookup.
  • [Confirm Collection](https://docs.miden.co/payment-gateway/collect/virtual-accounts/confirm-collection.md): Description This is endpoint is used to confirm webhook sent to the webhook url you registered. It adds extra layer of comfort to confirm that the notification actually came from us. EventId from the wenhook should be used to confirm the transaction
  • [Get Collections (Virtual Accounts)](https://docs.miden.co/payment-gateway/collect/virtual-accounts/get-collections-virtual-accounts.md): Description Retrieves a paginated list of transactions (collections) made into virtual accounts. This endpoint provides visibility into all inflows into your virtual accounts, including payer details, source bank information, transaction status, and settlement details. It is primarily used for reconciliation, reporting, and tracking customer payments. Usage Use this endpoint when you need to: track payments received via virtual accounts reconcile incoming transfers with your system view payer (sender) details such as account name and bank monitor settlement status ( creditPosted ) filter transactions by virtual account This is a collection retrieval endpoint for bank transfers (virtual accounts) . Notes Each record represents a bank transfer into a virtual account . creditPosted = true means funds have been successfully settled to the merchant. transactionAmount and settledAmount are typically equal but may differ due to fees or adjustments. The provider field indicates the banking infrastructure used (e.g., Providus). Transactions are returned in paginated format for efficient querying.
• [Card Payments](https://docs.miden.co/payment-gateway/checkout/card-payments.md): Overview The Card Payments module enables merchants to securely collect payments from customers using cards across supported currencies. It provides a complete transaction lifecycle including authorization, customer authentication (OTP or 3DS), capture, reversal, and reconciliation. The system dynamically determines the required validation method based on factors such as currency, issuing bank, and risk rules, ensuring both compliance and optimal user experience. All card transactions are standardized into a unified collections layer for tracking and reporting. Card Details Encryption Guide Card details must be encrypted before being sent to the API. The encryption method used is AES-256-CBC with PKCS7 padding . The card payload should first be serialized as JSON, then encrypted using: Algorithm: AES Mode: CBC Key size: 256 bits Padding: PKCS7 Key: First 16 characters of the uniqueKey after removing hyphens IV: Last 16 characters of the uniqueKey after removing hyphens Output: Base64 encrypted string Example card payload: JSON { "pan": "5061050254756707864", "expiryDate": "06/26", "cvv": "111", "cardScheme": "Verve", "pin": "1111", "nameOnCard": "Jane Doe" } Before encryption, remove hyphens from the uniqueKey : uniqueKey = uniqueKey.replace("-", "") Then derive: secretKey = first 16 characters of uniqueKey ivKey = last 16 characters of uniqueKey The encrypted result should be sent as the encrypted card data value. JavaScript Encryption JavaScript function encryptStringAES(plainText, secretKey, ivKey) { const key = CryptoJS.enc.Utf8.parse(secretKey); const iv = CryptoJS.enc.Utf8.parse(ivKey); const encrypted = CryptoJS.AES.encrypt( CryptoJS.enc.Utf8.parse(plainText), key, { keySize: 256 / 8, iv: iv, mode: CryptoJS.mode.CBC, padding: CryptoJS.pad.Pkcs7 } ); return encrypted.toString(); } const cardData = { pan: "5061050254756707864", expiryDate: "06/26", cvv: "111", cardScheme: "Verve", pin: "1111", nameOnCard: "Jane Doe" }; const unique = uniqueKey.replaceAll("-", ""); const secretKey = unique.slice(0, 16); const ivKey = unique.slice(-16); const serializedData = JSON.stringify(cardData); const encryptedCardData = encryptStringAES(serializedData, secretKey, ivKey); console.log(encryptedCardData); console.log(encryptedCardData); .NET Core Encryption C# using System.Security.Cryptography; using System.Text; using System.Text.Json; public static class CardEncryptionHelper { public static string EncryptCardData(object cardData, string uniqueKey) { var cleanedUniqueKey = uniqueKey.Replace("-", ""); var secretKey = cleanedUniqueKey[..16]; var ivKey = cleanedUniqueKey[^16..]; var plainText = JsonSerializer.Serialize(cardData); return EncryptStringAes(plainText, secretKey, ivKey); } private static string EncryptStringAes(string plainText, string secretKey, string ivKey) { var keyBytes = Encoding.UTF8.GetBytes(secretKey); var ivBytes = Encoding.UTF8.GetBytes(ivKey); using var aes = Aes.Create(); aes.Key = keyBytes; aes.IV = ivBytes; aes.Mode = CipherMode.CBC; aes.Padding = PaddingMode.PKCS7; using var encryptor = aes.CreateEncryptor(); var plainBytes = Encoding.UTF8.GetBytes(plainText); var encryptedBytes = encryptor.TransformFinalBlock(plainBytes, 0, plainBytes.Length); return Convert.ToBase64String(encryptedBytes); } } } Usage: C# var cardData = new { pan = "5061050254756707864", expiryDate = "06/26", cvv = "111", cardScheme = "Verve", pin = "1111", nameOnCard = "Jane Doe" }; var encryptedCardData = CardEncryptionHelper.EncryptCardData(cardData, uniqueKey); PHP Encryption PHP <?php function encryptCardData($cardData, $uniqueKey) { $cleanedUniqueKey = str_replace('-', '', $uniqueKey); $secretKey = substr($cleanedUniqueKey, 0, 16); $ivKey = substr($cleanedUniqueKey, -16); $plainText = json_encode($cardData); return openssl_encrypt( $plainText, 'AES-128-CBC', $secretKey, OPENSSL_RAW_DATA, $ivKey ); } $cardData = [ "pan" => "5061050254756707864", "expiryDate" => "06/26", "cvv" => "111", "cardScheme" => "Verve", "pin" => "1111", "nameOnCard" => "Jane Doe" ]; $encryptedRaw = encryptCardData($cardData, $uniqueKey); $encryptedCardData = base64_encode($encryptedRaw); echo $encryptedCardData; echo $encryptedCardData; Important Security Notes Card data such as PAN, CVV, PIN, and expiry date is highly sensitive. It must never be logged, stored in plain text, exposed in browser console logs, or transmitted outside secure HTTPS channels. The encrypted payload should be generated only at the point of submission and sent directly to the API.
  • [USD](https://docs.miden.co/payment-gateway/checkout/card-payments/usd.md): Overview USD Card payments follow a 3DS-first authentication model , designed to meet international card scheme requirements and reduce fraud risk. Transactions may either proceed frictionlessly or require a 3DS challenge , where the customer is redirected to their bank’s authentication page. Once authentication is completed, the transaction is authorized and can then be captured (fully or partially). This flow is typically redirect-based and requires handling of threeDsHtml or redirect URLs to complete authentication.
    • [Authorize Card - ThreeDs Validation Not Required](https://docs.miden.co/payment-gateway/checkout/card-payments/usd/authorize-card-threeds-validation-not-required.md): Description Processes a card payment authorization where additional authentication (3D Secure or OTP) is not required. This endpoint charges the customer’s card using the provided encrypted card details and completes the authorization immediately when no further validation is needed. Usage Use this endpoint when you need to: process a card payment without 3DS authentication complete a direct card charge using encrypted card details handle low-risk transactions that do not require step-up verification finalize a payment after collecting card details securely This is a card authorization operation (non-3DS flow) . Notes The bankCode returned here must be used when calling the Generate USSD Code endpoint. The ussdString is a template and contains a placeholder ( RefCode ) which will be replaced with an actual reference when generated. Supported banks may be updated over time, so it is recommended to fetch this list dynamically rather than hardcoding values. USSD payments are applicable only to NGN transactions .
    • [Authorize Card - ThreeDs Validation Required](https://docs.miden.co/payment-gateway/checkout/card-payments/usd/authorize-card-threeds-validation-required.md): Description Initiates a card payment authorization where 3D Secure authentication is required before the transaction can be completed. This endpoint starts the card authorization flow and returns the 3DS challenge details needed to present the authentication step to the customer.
    • [Complete ThreeDs Authorization](https://docs.miden.co/payment-gateway/checkout/card-payments/usd/complete-threeds-authorization.md): Description Finalizes a card payment after successful 3D Secure (3DS) authentication. This endpoint is used to complete the authorization process once the customer has finished the 3DS challenge. It confirms the authentication result and proceeds with the transaction. Usage Use this endpoint when you need to: complete a card payment after a 3DS challenge confirm the result of a 3DS authentication flow finalize a transaction that required additional verification proceed with authorization after customer authentication This is a 3DS authorization completion operation . Notes This endpoint should only be called after the customer completes the 3DS challenge. The orderId is obtained from the initial authorization response. A successful authenticationStatus confirms that the customer has been verified. Always handle redirects using the returned redirectUrl where applicable. You should rely on your configured postBackUrl for final transaction confirmation in asynchronous flows.
    • [Capture Card Authorization](https://docs.miden.co/payment-gateway/checkout/card-payments/usd/capture-card-authorization.md): Description Captures funds from a previously authorized card transaction. This endpoint is used to complete a payment after a successful authorization by transferring the authorized amount into a settled state. It also supports capturing only a portion of the authorized amount when needed. Usage Use this endpoint when you need to: capture funds from a previously authorized card transaction complete a delayed payment after authorization settle a transaction after successful card authorization (with or without 3DS) capture a partial amount from an authorized transaction This is a card capture operation . Notes This endpoint is used in two-step payment flows (authorize → capture). Partial capture is supported. Example: If $100 is authorized, you can capture $50. The total captured amount must not exceed the original authorized amount. Depending on configuration, multiple captures may or may not be allowed. Ensure the authorization is still valid before attempting capture. Use a unique paymentReference for each capture request to avoid duplication.
    • [Void (Reverse) Card Authorization](https://docs.miden.co/payment-gateway/checkout/card-payments/usd/void-reverse-card-authorization.md): Description Voids a previously authorized card transaction before capture. This endpoint is used to cancel an authorization hold on a customer’s card when you no longer want to proceed with the payment. Once voided, the authorized amount is released and the transaction will not be captured.
    • [Update Card Authorization](https://docs.miden.co/payment-gateway/checkout/card-payments/usd/update-card-authorization.md): Description Updates the amount of a previously authorized card transaction. This endpoint allows you to modify the authorized amount before the transaction is captured. It is typically used when the final charge amount differs from the initially authorized amount.
  • [NGN](https://docs.miden.co/payment-gateway/checkout/card-payments/ngn.md): Overview NGN Card payments primarily rely on OTP-based authentication , providing a localized and familiar experience for customers. After initiating a transaction, the system may require the customer to enter a one-time password sent by their bank. In some cases, 3DS authentication may still be triggered depending on issuer rules. Once validation is successful, the transaction is authorized and can be captured. NGN flows are generally more API-driven (non-redirect) compared to USD, making them suitable for in-app payment experiences.
    • [Authorize Card - OTP Validation Required](https://docs.miden.co/payment-gateway/checkout/card-payments/ngn/authorize-card-otp-validation-required.md): Description Initiates a card payment authorization that requires OTP validation before completion. This endpoint validates the card details and places the transaction in a pending state, where the customer must complete OTP verification to finalize the authorization. Usage Use this endpoint when you need to: initiate a card payment that requires OTP verification process NGN card transactions with bank-issued OTP validation handle transactions that require additional customer authentication begin a secure authorization flow before final confirmation This is a card authorization operation (OTP flow) . Notes This flow is specific to NGN card transactions . A value of otpValidationRequired = true means the transaction is not yet complete. You must call the OTP validation endpoint (next step) to finalize the transaction. No funds are captured until OTP verification is successful. Always listen to the configured postBackUrl for final transaction status updates.
    • [Authorize Card - ThreeDs Validation Required](https://docs.miden.co/payment-gateway/checkout/card-payments/ngn/authorize-card-threeds-validation-required.md): Description Initiates an NGN card payment authorization that requires 3D Secure (3DS) authentication before the transaction can be completed. This endpoint validates the card details, attempts authorization, and returns a 3DS challenge payload when the issuer requires additional customer verification. The transaction remains incomplete until the customer successfully completes the authentication step. Usage Use this endpoint when you need to: initiate an NGN card payment that requires 3DS authentication present the customer with a 3DS challenge during card payment process issuer-mandated step-up authentication flows continue a secure card authorization flow before final confirmation This is a card authorization operation (3DS flow) . Notes This flow applies to NGN card transactions where issuer authentication is required. A value of threeDsInteractionRequired = true means the transaction cannot be completed until the customer finishes the 3DS challenge. paresStatus = "C" indicates that a challenge flow must be completed before the authorization can proceed. Fields such as md , cReq , termUrl , action , and pareq may vary by processor and authentication version. Some may be returned as null even though equivalent values are embedded in rawHtml . For most integrations, rawHtml is the simplest way to launch the 3DS challenge. For custom implementations, use the processor-specific fields returned in threeDsHtml , especially stepUpUrl and any available authentication payload values. You should listen to the configured postBackUrl for the final transaction outcome after the authentication flow completes.
    • [Complete ThreeDs Authorization](https://docs.miden.co/payment-gateway/checkout/card-payments/ngn/complete-threeds-authorization.md): Description Finalizes a card authorization after a successful 3D Secure (3DS) authentication. This endpoint confirms the result of the 3DS challenge and completes the authorization process for NGN card transactions. It transitions the transaction from a pending authentication state to a confirmed authorization. Usage Use this endpoint when you need to: complete a card payment after a 3DS challenge confirm the result of a 3DS authentication flow finalize an NGN card authorization requiring step-up verification proceed with a transaction after successful customer authentication This is a 3DS authorization completion operation . Notes This endpoint should only be called after the customer completes the 3DS challenge. The orderId is obtained from the initial authorization response. A successful authenticationStatus confirms that the customer has been verified. Always handle user redirection using the returned redirectUrl . This flow applies to NGN card transactions requiring 3DS authentication . You should rely on your configured postBackUrl for final transaction confirmation in asynchronous flows.
    • [Validate OTP](https://docs.miden.co/payment-gateway/checkout/card-payments/ngn/validate-otp.md): Description Validates the One-Time Password (OTP) submitted for a pending NGN card authorization. This endpoint is used to complete an OTP-based card authorization flow after the customer receives and submits the verification code issued by their bank. A successful validation confirms the transaction and allows it to proceed.
    • [Resend OTP](https://docs.miden.co/payment-gateway/checkout/card-payments/ngn/resend-otp.md): Description Resends the One-Time Password (OTP) required to complete a pending card authorization. This endpoint is used when a customer did not receive or has lost the initial OTP during an NGN card payment flow. It triggers a new OTP to be sent via the issuer’s configured delivery channel.
  • [Get Collections (Cards)](https://docs.miden.co/payment-gateway/checkout/card-payments/get-collections-cards.md): Description Retrieves a paginated list of card collection transactions based on specified filters such as channel, transaction type, currency, and status. This endpoint provides visibility into the full lifecycle of card transactions, including authorizations, captures, refunds, and reversals , along with settlement and reconciliation details. Usage Use this endpoint to: fetch card payment transactions track transaction lifecycle (authorization → capture → refund/void) reconcile settlements and fees monitor transaction statuses audit card payment activity Notes This endpoint supports full transaction lifecycle tracking . Use filters to narrow results for reporting and reconciliation. Pagination is required for large datasets. For card transactions: Authorization does not move funds Capture triggers settlement Refund reverses settled funds Key Insights A single payment flow may produce multiple records : Authorization Capture Refund / Partial Refund Partial refunds and captures are reflected as separate transactions linked via IDs settledAmount may differ from transactionAmount due to processing adjustments. creditPosted = true confirms funds have been settled to the merchant.
• [Non-Card Payments](https://docs.miden.co/payment-gateway/checkout/non-card-payments.md): Overview The Non-Card Payments module enables merchants to collect funds through alternative payment methods that do not require card details. These channels are designed to support local payment behaviors and asynchronous transaction flows, while still providing consistent tracking and settlement through the collections system. Non-card payments typically involve generating a payment instrument (such as a virtual account, USSD code, or payment link) which the customer uses to complete the transaction. Once payment is made, the system confirms and records the transaction for reconciliation. Virtual Account (Bank Transfer) Virtual Account payments allow merchants to receive funds via bank transfer using dynamically or statically assigned account numbers. A dedicated account number is generated for a customer or transaction, and the customer completes payment by transferring funds from their bank. The system detects the inflow, validates it, and updates the transaction status accordingly. This method is ideal for asynchronous payments , where the customer may complete the transfer at a later time, and is widely used for local bank-based collections. USSD Payments USSD payments enable customers to complete transactions by dialing a short code on their mobile phone. A USSD string is generated and tied to a transaction reference. The customer dials the code and follows their bank’s USSD prompts to authorize the payment. Once completed, the transaction is confirmed and recorded. This channel is primarily available for NGN transactions and is useful for customers without internet access or smartphones. Payment Links (Hosted Checkout) Payment Links allow merchants to collect payments by sharing a hosted checkout URL with customers. The link directs the customer to a secure payment page where they can choose from available payment methods (such as card or transfer). This approach removes the need for direct integration on the merchant’s frontend and is ideal for remote payments, social commerce, and invoicing. Payment links provide a flexible and user-friendly checkout experience , while still feeding all transactions into the unified collections system.
  • [Generate USSD Code](https://docs.miden.co/payment-gateway/checkout/non-card-payments/ussd-collections/generate-ussd-code.md): Description Generates a USSD payment reference and string that can be used to complete a transaction via mobile devices. This endpoint provides the necessary USSD details linked to an existing payment, allowing customers to dial a short code on their mobile device. Usage Use this endpoint when you need to: enable USSD-based payment for a transaction provide customers with a dialable USSD string for payment support offline or low-internet payment channels complete payments through bank USSD services This is a USSD payment initiation operation . Notes USSD payments are only supported for NGN transactions . The generated ussdString should be presented clearly to the customer for dialing. Each USSD request is tied to an existing payment and cannot be reused across multiple transactions. Availability of USSD depends on the selected bank and provider support.
  • [Get USSD Banks](https://docs.miden.co/payment-gateway/checkout/non-card-payments/ussd-collections/get-ussd-banks.md): Description Retrieves the list of supported banks available for USSD payments. Each bank entry includes the bank code and a USSD format that can be used to guide customers when completing payments via mobile banking. Usage Use this endpoint when you need to: display available banks for USSD payment selection allow customers choose their preferred bank for USSD checkout dynamically populate bank options in your UI obtain valid bank codes required for USSD payment generation This is a USSD bank discovery operation . Notes The bankCode returned here must be used when calling the Generate USSD Code endpoint. The ussdString is a template and contains a placeholder ( RefCode ) which will be replaced with an actual reference when generated. Supported banks may be updated over time, so it is recommended to fetch this list dynamically rather than hardcoding values. USSD payments are applicable only to NGN transactions .
  • [Get Collections (USSD)](https://docs.miden.co/payment-gateway/checkout/non-card-payments/ussd-collections/get-collections-ussd.md): Description Retrieves a list of USSD payment collections processed through the system. This endpoint returns transaction records for payments completed via the USSD channel, including status, amount, references, and settlement details. Usage Use this endpoint when you need to: retrieve USSD payment transactions monitor collection activity via USSD channel reconcile payments using transaction and merchant references filter collections by channel, currency, or status This is a USSD collections retrieval operation . Notes This endpoint supports pagination using currentPage , pageSize , and totalPages . Only transactions processed via the USSD channel are returned when Channel=Ussd is specified. Use merchantReference and transactionReference for reconciliation and tracking. A transaction with creditPosted = true indicates that funds have been successfully credited. Additional transaction fields may be returned but can be ignored if not relevant to your integration.
• [Invoicing](https://docs.miden.co/payment-gateway/invoicing.md): The Invoicing module enables businesses to create, manage, and track invoices for payments across supported channels. It provides a structured way to bill customers, define payment terms, and monitor payment status in real-time. With this module, you can generate invoices with itemized details, apply discounts and taxes, and choose preferred payment methods such as payment links or direct transfers. It also supports draft management, allowing invoices to be saved, updated, and finalized before being shared with customers. Additionally, the module provides endpoints to retrieve invoices, track their status (e.g., pending, paid), and access payment links and receipts. This ensures full visibility into billing operations and simplifies reconciliation and reporting.
  • [Create Invoice](https://docs.miden.co/payment-gateway/invoicing/create-invoice.md): Description Creates a new invoice for a customer. This endpoint allows you to generate an invoice for goods or services, define the payment method, configure the payment schedule, and include itemized charges, discounts, shipping fees, and tax. Usage Use this endpoint when you need to: create a new invoice for a customer bill a customer for one or more items or services configure invoice payment through cash or payment link apply discounts, shipping fees, and tax to an invoice This is an invoice creation operation . Notes invoiceId is only needed when updating or saving an existing draft invoice. The invoice supports itemized billing through the items array. PaymentLink can be used when the customer is expected to pay online. OneOff creates a single-payment invoice, while Split can be used for installment-based billing. Discount, shipping fee, and tax are optional and can be used to adjust the final invoice amount.
  • [Save Invoice Draft](https://docs.miden.co/payment-gateway/invoicing/save-invoice-draft.md): Description Saves an invoice as a draft. This endpoint allows you to create or update an invoice in draft state before finalizing or sending it to a customer. Usage Use this endpoint when you need to: save an invoice without sending it to a customer create a draft invoice for later completion update an existing draft invoice This is a draft invoice operation . Notes This endpoint does not trigger payment or customer notification. Draft invoices can be edited and finalized later. Use invoiceId to update an existing draft. Supports the same structure as invoice creation but stores it in draft state instead of processing it.
  • [Update invoice Draft](https://docs.miden.co/payment-gateway/invoicing/update-invoice-draft.md): Description Updates an existing invoice draft. This endpoint allows you to modify the details of a previously saved draft invoice before it is finalized or sent to a customer.
  • [Get Invoices](https://docs.miden.co/payment-gateway/invoicing/get-invoices.md): Description Retrieves a list of invoices. This endpoint allows you to fetch all invoices created within your organization, with support for filtering by invoice details and pagination.
  • [Get Invoice by ID](https://docs.miden.co/payment-gateway/invoicing/get-invoice-by-id.md): Description Retrieves the details of a specific invoice. This endpoint allows you to fetch a single invoice using its unique identifier, including all associated items, payment details, and metadata.
  • [Get Invoice by Number](https://docs.miden.co/payment-gateway/invoicing/get-invoice-by-number.md): Description Retrieves the details of a specific invoice using its invoice number. This endpoint allows you to fetch a single invoice by its human-readable invoice number, including all associated items, totals, and payment details.
• [Accrual Wallets](https://docs.miden.co/payment-gateway/accrual-wallets.md): Accrual Wallets The Accrual Wallets section provides visibility and control over funds collected through the platform. It represents the financial position of a merchant or organization across different currencies. Each wallet reflects two key balances: Ledger Balance – the total amount collected, including both settled and unsettled transactions Available Balance – the portion of funds that has been settled and is available for use This section includes endpoints for retrieving wallet details, tracking transactions, generating statements, and monitoring settlement status, enabling accurate reconciliation and financial reporting.
  • [Get Wallets](https://docs.miden.co/payment-gateway/accrual-wallets/get-wallets.md): Description Retrieves the list of accrual wallets associated with the merchant. Accrual wallets represent the merchant’s position on the accrual ledger across supported currencies. Each wallet provides visibility into the merchant’s total collected balance, available settled balance, unclear balance, liens, and other wallet-level attributes. In this context, the wallet response includes both the overall ledger position and the portion that is currently available for use or withdrawal. Usage Use this endpoint when you need to: retrieve all accrual wallets for a merchant view wallet balances across currencies check available settled balance monitor unclear or pending balances track wallet status and last transaction activity This is a wallet retrieval operation . Notes walletBalance represents the ledger balance — the merchant’s total collected position, whether settled or not. walletAvailableBalance represents the available balance — the portion that has been settled and is currently available. walletUnclearBalance represents collected funds that are not yet fully cleared or settled. lienAmount represents funds under restriction and not currently available for use. Each currency is returned as a separate accrual wallet. In the sample response, separate wallets exist for NGN , USD , USDC , and USDT .
  • [Get Wallet Transactions](https://docs.miden.co/payment-gateway/accrual-wallets/get-wallet-transactions.md): Description Retrieves a paginated list of transactions posted to a specific accrual wallet within a selected date range. This endpoint returns wallet-level ledger entries, including credits, debits, charges, payouts, and collection postings. It is used to track wallet activity over time and provides the transaction records needed for audit, reconciliation, and statement generation.
  • [Get Wallet Statement](https://docs.miden.co/payment-gateway/accrual-wallets/get-wallet-statement.md)
  • [Get Settlement](https://docs.miden.co/payment-gateway/accrual-wallets/get-settlement.md): Description Retrieves a paginated list of value-dated accrual transactions within a specified date range. This endpoint returns transactions based on their settlement state using the Cleared flag. It can be used to fetch either transactions that have already been cleared into available balance or transactions that are still uncleared and pending settlement.
• [SDKs](https://docs.miden.co/payment-gateway/sdks.md): Overview In this section, we outline the libraries we support for payment acceptance, designed primarily for customers integrating our payment solutions through SDKs. React Angular Vue
  • [Angular](https://docs.miden.co/payment-gateway/sdks/angular.md): 1. Introduction The Angular Checkout SDK allows merchants to integrate secure payment checkout flows directly into Angular applications. The SDK supports multiple checkout options: Checkout Button Embedded Checkout Card Checkout Iframe It is designed for Angular applications using Angular CLI, Nx, NgModules, or Standalone Components. 2. Installation Install the SDK using your preferred package manager. npm ```bash npm install @miden-npm/angular yarn Bash yarn add @miden-npm/angular pnpm Bash pnpm add @miden-npm/angular 3. Import Styles Add the SDK stylesheet to your global stylesheet. For styles.css or styles.scss : CSS @import "@miden-npm/angular/dist/styles.css"; 4. Angular Setup 4.1 NgModule Setup If your Angular app uses AppModule , import the SDK module. JavaScript import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { BzpCheckoutModule } from '@miden-npm/angular'; import { AppComponent } from './app.component'; @NgModule({ declarations: [AppComponent], imports: [ BrowserModule, BzpCheckoutModule ], bootstrap: [AppComponent] }) export class AppModule {} 4.2 Standalone Component Setup If your Angular app uses standalone components, import the required SDK components. JavaScript import { Component } from '@angular/core'; import { BzpCheckoutCardComponent } from '@miden-npm/angular'; @Component({ selector: 'app-root', standalone: true, imports: [BzpCheckoutCardComponent], templateUrl: './app.component.html' }) export class AppComponent {} Note: Component export names may differ depending on your SDK build. If you export a single module only, use BzpCheckoutModule . 5. Quick Start The example below shows how to render an embedded checkout card. app.component.ts JavaScript import { Component } from '@angular/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html' }) export class AppComponent { secretKey = 'YOUR_SECRET_KEY'; paymentObject = { merchantName: 'Raymahni LLC', amount: 120, currency: 'NGN', email: 'customer@example.com', phoneNumber: '07026536637', narration: 'Order payment', redirectUrl: 'https://merchantapp.com/payment-success' }; onTransactionUpdate(event: any) { console.log('Transaction update:', event); if (event.status === 'success') { // Verify payment on your backend before fulfilling the order } if (event.status === 'failed') { // Show failure message to the customer } } onEmitMessage(message: any) { console.log('SDK message:', message); } } app.component.html JavaScript [secretKey]="secretKey" [paymentObject]="paymentObject" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-card> 6. Configuration 6.1 Common Component Props These props are available across the checkout components. Title Description Title Description Title Prop Type Required Default Description secretKey string Yes — Merchant SDK key paymentObject object Yes — Payment details environment `"sandbox" "production"` No "sandbox" 7. Payment Object The paymentObject contains the transaction details required to initialize checkout. JavaScript const paymentObject = { merchantName: 'Raymahni LLC', amount: 120, currency: 'NGN', email: 'customer@example.com', phoneNumber: '07026536637', narration: 'Order #123', redirectUrl: 'https://merchantapp.com/payment-success' }; Payment Object Fields Title Description Title Description Field Type Required Description merchantName string Yes Merchant display name amount number Yes Transaction amount currency string Yes Currency code, for example "NGN" email string Yes Customer email address phoneNumber string Yes Customer phone number narration string Yes Payment description redirectUrl string Yes URL where the customer is redirected after payment Recommended TypeScript Interface JavaScript export interface PaymentObject { merchantName: string; amount: number; currency: string; email: string; phoneNumber: string; narration: string; redirectUrl: string; } 8. Components 8.1 Checkout Button The checkout button renders a button that starts the payment flow. It supports two modes: redirect iframe Props Title Description Title Description Title Prop Type Required Default Description secretKey string Yes — Merchant SDK key paymentObject object Yes — Payment details mode `"redirect" "iframe"` No "redirect" environment `"sandbox" "production"` No "sandbox" Redirect Mode HTML [secretKey]="secretKey" [paymentObject]="paymentObject" mode="redirect" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-button> [secretKey]="secretKey" [paymentObject]="paymentObject" mode="redirect" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-button> Iframe Mode HTML [secretKey]="secretKey" [paymentObject]="paymentObject" mode="iframe" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-button> [secretKey]="secretKey" [paymentObject]="paymentObject" mode="iframe" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-button> Behavior Title Description Mode Behavior redirect Opens checkout on a new page iframe Opens checkout inside an iframe overlay 8.2 Checkout Card The checkout card displays an embedded checkout form directly inside the merchant application. Example HTML [secretKey]="secretKey" [paymentObject]="paymentObject" environment="production" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-card> [secretKey]="secretKey" [paymentObject]="paymentObject" environment="production" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-card> Description Use this component when you want the checkout experience to appear directly inside your page. The checkout card can collect payment details and emit transaction updates after payment actions. 8.3 Checkout Iframe The checkout iframe embeds the checkout page directly inside your Angular application. Example HTML [secretKey]="secretKey" [paymentObject]="paymentObject" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-iframe> [secretKey]="secretKey" [paymentObject]="paymentObject" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-iframe> Description Use this component when you want to display checkout inline through an iframe. The iframe component handles checkout communication and emits transaction updates to the parent Angular app. 9. Handling Responses The SDK provides events that help your application respond to payment updates and SDK messages. 9.1 Handling Transaction Updates All checkout components emit a transactionUpdate event when the transaction status changes. Template Example HTML [secretKey]="secretKey" [paymentObject]="paymentObject" (transactionUpdate)="onTransactionUpdate($event)"> </bzp-checkout-card> [secretKey]="secretKey" [paymentObject]="paymentObject" (transactionUpdate)="onTransactionUpdate($event)"> </bzp-checkout-card> Component Example JavaScript onTransactionUpdate(event: any) { console.log('Transaction status:', event.status); if (event.status === 'success') { // Payment was successful // Verify payment on your backend before fulfilling the order } if (event.status === 'failed') { // Payment failed } if (event.status === 'pending') { // Payment is still pending } } Example Event Payload JSON { "status": "success", "reference": "TXN_12345", "message": "Payment completed successfully" } Recommended TypeScript Interface JavaScript export interface TransactionUpdateEvent { status: 'success' | 'failed' | 'pending'; reference?: string; message?: string; } 9.2 Handling SDK Messages All checkout components emit an emitMessage event for general SDK notifications. Template Example HTML [secretKey]="secretKey" [paymentObject]="paymentObject" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-card> [secretKey]="secretKey" [paymentObject]="paymentObject" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-card> Component Example JavaScript onEmitMessage(message: any) { const { state, message: text } = message; console.log(`[${state}]`, text); } Example Message Payload JSON { "state": "success", "message": "Payment initialized successfully" } Recommended TypeScript Interface JavaScript export interface SdkMessageEvent { state: 'success' | 'error' | 'info' | 'warning'; message: string; } 10. Redirect Callback Handling If you use redirect mode, the SDK redirects the customer to the redirectUrl provided in the paymentObject . Example Payment Object JavaScript paymentObject = { merchantName: 'Raymahni LLC', amount: 120, currency: 'NGN', email: 'customer@example.com', phoneNumber: '07026536637', narration: 'Order #123', redirectUrl: 'https://merchantapp.com/payment-success' }; After checkout, the customer is redirected to the specified URL. Your success page can read query parameters from the URL. JavaScript const urlParams = new URLSearchParams(window.location.search); const status = urlParams.get('status'); const reference = urlParams.get('reference'); if (status === 'success' && reference) { // Send the reference to your backend for verification } 11. Iframe Response Handling When checkout runs inside an iframe, your application can receive updates in two ways: Using the Angular transactionUpdate event Listening for browser postMessage events Using transactionUpdate HTML [secretKey]="secretKey" [paymentObject]="paymentObject" (transactionUpdate)="onTransactionUpdate($event)"> </bzp-checkout-iframe> [secretKey]="secretKey" [paymentObject]="paymentObject" (transactionUpdate)="onTransactionUpdate($event)"> </bzp-checkout-iframe> Using postMessage JavaScript window.addEventListener('message', (event) => { if (event.data?.type === 'transactionUpdate') { console.log('Transaction status:', event.data.status); console.log('Transaction reference:', event.data.reference); } }); Example postMessage Payload JSON { "type": "transactionUpdate", "status": "success", "reference": "TXN_12345", "message": "Payment completed successfully" } 12. Environment Configuration The SDK supports sandbox and production environments. Title Description Value Description sandbox Use for testing transactions production Use for live transactions Default environment: JavaScript sandbox Example HTML [secretKey]="secretKey" [paymentObject]="paymentObject" environment="production"> </bzp-checkout-card> [secretKey]="secretKey" [paymentObject]="paymentObject" environment="production"> </bzp-checkout-card> 13. Recommended Payment Verification Flow For security, do not fulfill an order based only on frontend events. Use the frontend event as a notification, then verify the transaction on your backend. Recommended flow: Customer starts checkout from your Angular app. SDK initializes payment. Customer completes payment. SDK emits a transaction update with a transaction reference. Your frontend sends the reference to your backend. Your backend verifies the transaction. Your backend confirms the payment status. You fulfill the customer’s order only after backend verification succeeds. Example: JavaScript onTransactionUpdate(event: any) { if (event.status === 'success' && event.reference) { this.verifyPayment(event.reference); } } verifyPayment(reference: string) { // Send reference to your backend API // Example: // POST /api/payments/verify } 14. Security Notes Follow these security recommendations when using the SDK: Do not expose private secret keys in frontend code. Use a public/client SDK key on the frontend if available. Verify all successful payments on your backend. Use HTTPS redirect URLs in production. Do not fulfill orders from frontend events alone. Store production credentials securely. Use sandbox for testing and production only for live payments. Important: If secretKey is a private server-side key, do not use it directly inside Angular code. Consider using a public client key instead. 15. Troubleshooting 15.1 Component is not recognized Error example: JSON 'bzp-checkout-card' is not a known element Possible cause: The SDK module or component was not imported. Fix: JavaScript import { BzpCheckoutModule } from '@miden-npm/angular'; Then add it to your Angular module imports. JavaScript imports: [ BzpCheckoutModule ] 15.2 Styles are not applied Possible cause: The SDK stylesheet was not imported. Fix: CSS @import "@miden-npm/angular/dist/styles.css"; 15.3 transactionUpdate is not firing Possible causes: Event binding is missing Payment was not initialized Invalid payment object Invalid SDK key Network issue Check that your component includes: HTML (transactionUpdate)="onTransactionUpdate($event)" (transactionUpdate)="onTransactionUpdate($event)" 15.4 Redirect is not working Possible causes: redirectUrl is missing redirectUrl is not a valid URL Production redirect URL is not HTTPS Redirect domain is not allowed Fix: JavaScript redirectUrl: 'https://merchantapp.com/payment-success' 15.5 Iframe is not loading Possible causes: Invalid environment Invalid payment object Network or browser restriction Parent domain is not allowed Check your browser console for errors. 16. Full Example app.component.ts JavaScript import { Component } from '@angular/core'; interface PaymentObject { merchantName: string; amount: number; currency: string; email: string; phoneNumber: string; narration: string; redirectUrl: string; } interface TransactionUpdateEvent { status: 'success' | 'failed' | 'pending'; reference?: string; message?: string; } interface SdkMessageEvent { state: 'success' | 'error' | 'info' | 'warning'; message: string; } @Component({ selector: 'app-root', templateUrl: './app.component.html' }) export class AppComponent { secretKey = 'YOUR_SECRET_KEY'; paymentObject: PaymentObject = { merchantName: 'Raymahni LLC', amount: 120, currency: 'NGN', email: 'customer@example.com', phoneNumber: '07026536637', narration: 'Order #123', redirectUrl: 'https://merchantapp.com/payment-success' }; onTransactionUpdate(event: TransactionUpdateEvent) { console.log('Transaction update:', event); if (event.status === 'success' && event.reference) { this.verifyPayment(event.reference); } if (event.status === 'failed') { console.log('Payment failed:', event.message); } if (event.status === 'pending') { console.log('Payment pending:', event.reference); } } onEmitMessage(event: SdkMessageEvent) { console.log(`[${event.state}] ${event.message}`); } verifyPayment(reference: string) { console.log('Verify payment on backend:', reference); // Send the transaction reference to your backend. // Do not fulfill the order until backend verification succeeds. } } app.component.html HTML [secretKey]="secretKey" [paymentObject]="paymentObject" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-card> [secretKey]="secretKey" [paymentObject]="paymentObject" environment="sandbox" (transactionUpdate)="onTransactionUpdate($event)" (emitMessage)="onEmitMessage($event)"> </bzp-checkout-card> 17. Support For support, contact the development team or open an issue in the project repository. Include the following details when reporting an issue: SDK version Angular version Browser Environment: sandbox or production Error message Steps to reproduce the issue 18. Changelog Document SDK changes using semantic versioning. Example: v1.0.0 Initial Angular Checkout SDK release Added checkout button Added checkout card Added checkout iframe Added transaction update events
  • [Vue](https://docs.miden.co/payment-gateway/sdks/vue.md): 1. Introduction The Vue Checkout SDK allows merchants to integrate secure payment checkout flows directly into Vue applications. The SDK supports multiple checkout experiences: Checkout Button Embedded Checkout Card Embedded Checkout Iframe The SDK is designed for: Vue 3+ Vite Nuxt 3 TypeScript and JavaScript projects 2. Requirements Before integrating the SDK, ensure your environment meets the following requirements: Vue 3+ Node.js 18+ Active merchant account Valid SDK key 3. Installation Install the SDK using your preferred package manager. npm Bash npm install @miden-npm/vue yarn Bash yarn add @miden-npm/vue pnpm Bash pnpm add @miden-npm/vue 4. Import Styles Import the SDK stylesheet once at the root of your application. main.ts Ts import { createApp } from "vue"; import App from "./App.vue"; import "@miden-npm/vue/dist/styles.css"; createApp(App).mount("#app"); 5. Quick Start The example below shows how to render an embedded checkout card. App.vue Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" environment="sandbox" @transactionUpdate="handleTransactionUpdate" @emitMessage="handleMessage" /> </template> <script setup lang="ts"> import { BzpCheckoutCard } from "@miden-npm/vue"; const secretKey = "YOUR_SECRET_KEY"; const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order payment", redirectUrl: "https://merchantapp.com/payment-success", }; const handleTransactionUpdate = (event: any) => { console.log("Transaction update:", event); if (event.status === "success") { // Verify payment on your backend } if (event.status === "failed") { // Handle failed payment } if (event.status === "pending") { // Handle pending payment } }; const handleMessage = (message: any) => { console.log("SDK message:", message); }; </script> 6. Configuration 6.1 Common Props These props are supported across all SDK components. Title Description Title Description Title Prop Type Required Default Description secretKey string Yes — Merchant SDK key paymentObject object Yes — Payment details object environment `"sandbox" "production"` No "sandbox" 7. Payment Object The paymentObject contains the transaction information required to initialize checkout. Example Ts const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; Payment Object Fields Title Description Title Description Field Type Required Description merchantName string Yes Merchant display name amount number Yes Transaction amount currency string Yes Currency code email string Yes Customer email phoneNumber string Yes Customer phone number narration string Yes Payment description redirectUrl string Yes Redirect URL after payment Recommended TypeScript Interface Ts export interface PaymentObject { merchantName: string; amount: number; currency: string; email: string; phoneNumber: string; narration: string; redirectUrl: string; } 8. Components 8.1 Checkout Button The checkout button component renders a button that launches checkout. Supported modes: Redirect checkout Iframe checkout Props Title Description Title Description Title Prop Type Required Default Description secretKey string Yes — Merchant SDK key paymentObject object Yes — Payment details mode `"redirect" "iframe"` No "redirect" environment `"sandbox" "production"` No "sandbox" Redirect Mode Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" mode="redirect" environment="sandbox" /> </template> <script setup lang="ts"> import { BzpCheckoutButton } from "@miden-npm/vue"; const secretKey = "YOUR_SECRET_KEY"; const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; </script> Iframe Mode Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" mode="iframe" environment="sandbox" /> </template> <script setup lang="ts"> import { BzpCheckoutButton } from "@miden-npm/vue"; const secretKey = "YOUR_SECRET_KEY"; const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; </script> Behavior Title Description Mode Description redirect Opens checkout on a new page iframe Opens checkout inside an iframe overlay 8.2 Checkout Card The checkout card component renders a fully embedded checkout form directly inside your application. Example Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" environment="production" /> </template> <script setup lang="ts"> import { BzpCheckoutCard } from "@miden-npm/vue"; const secretKey = "YOUR_SECRET_KEY"; const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; </script> Description The checkout card allows merchants to embed payment fields directly inside their Vue application. The component handles: Card collection Payment initialization Payment status updates Secure checkout flow 8.3 Checkout Iframe The checkout iframe component embeds the checkout page directly into your application using an iframe. Example Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" environment="sandbox" /> </template> <script setup lang="ts"> import { BzpCheckoutIframe } from "@miden-npm/vue"; const secretKey = "YOUR_SECRET_KEY"; const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; </script> Description The iframe component is useful when merchants want checkout embedded inline within a page. The component automatically handles: Secure iframe communication Dynamic resizing Transaction updates 9. Handling Responses The SDK provides multiple ways to receive transaction updates and SDK messages. 9.1 Transaction Updates All checkout components emit a transactionUpdate event whenever the payment status changes. Example Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" @transactionUpdate="handleTransactionUpdate" /> </template> <script setup lang="ts"> const handleTransactionUpdate = (event: any) => { console.log("Transaction status:", event.status); if (event.status === "success") { // Handle successful payment } if (event.status === "failed") { // Handle failed payment } if (event.status === "pending") { // Handle pending payment } }; </script> Example Transaction Payload JSON { "status": "success", "reference": "TXN_12345", "message": "Payment completed successfully" } Recommended TypeScript Interface Ts export interface TransactionUpdateEvent { status: "success" | "failed" | "pending"; reference?: string; message?: string; } 9.2 SDK Messages All checkout components emit an emitMessage event. This event can be used to display SDK notifications or feedback to users. Example Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" @emitMessage="handleMessage" /> </template> <script setup lang="ts"> const handleMessage = (msg: any) => { const { state, message } = msg; console.log(`[${state.toUpperCase()}]`, message); }; </script> Example Message Payload JSON { "state": "success", "message": "Payment initialized successfully" } Recommended TypeScript Interface Ts export interface SdkMessageEvent { state: "success" | "error" | "info" | "warning"; message: string; } 10. Redirect Callback Handling If checkout uses redirect mode, the SDK redirects the customer to the redirectUrl specified in the paymentObject . Example Success Page Vue <script setup lang="ts"> const urlParams = new URLSearchParams(window.location.search); const status = urlParams.get("status"); const reference = urlParams.get("reference"); if (status === "success" && reference) { // Verify payment on your backend } </script> 11. Iframe Response Handling When checkout runs inside an iframe, your app can receive updates in two ways: Using the transactionUpdate event Listening for browser postMessage events Using transactionUpdate Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" @transactionUpdate="handleTransactionUpdate" /> </template> <script setup lang="ts"> const handleTransactionUpdate = (event: any) => { console.log(event); }; </script> Using postMessage Ts window.addEventListener("message", (event) => { if (event.data?.type === "transactionUpdate") { console.log("Transaction status:", event.data.status); console.log("Transaction reference:", event.data.reference); } }); Example postMessage Payload JSON { "type": "transactionUpdate", "status": "success", "reference": "TXN_12345", "message": "Payment completed successfully" } 12. Environment Configuration The SDK supports two environments. Title Description Value Description sandbox Testing environment production Live production environment Default Environment Ts sandbox 13. Nuxt 3 Usage If you are using Nuxt 3, load checkout components only on the client side. Example Vue <template> <ClientOnly> :secretKey="secretKey" :paymentObject="paymentObject" /> </ClientOnly> </template> This SDK relies on browser APIs and must run on the client side. 14. Recommended Payment Verification Flow Do not fulfill orders based only on frontend payment events. Always verify successful payments on your backend. Recommended Flow Customer starts checkout SDK initializes payment Customer completes payment SDK returns transaction reference Frontend sends reference to backend Backend verifies transaction Backend confirms payment status Merchant fulfills the order Example Ts const handleTransactionUpdate = async (event: any) => { if (event.status === "success" && event.reference) { await verifyPayment(event.reference); } }; const verifyPayment = async (reference: string) => { await fetch("/api/payments/verify", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ reference }), }); }; 15. Security Notes Follow these security best practices when integrating the SDK. Do not expose private server-side keys publicly Verify payments on your backend Use HTTPS redirect URLs in production Store production credentials securely Use environment variables for configuration Do not fulfill orders based only on frontend responses Environment Variable Example Env VITE_BZP_SECRET_KEY=YOUR_SECRET_KEY Vue Usage Ts const secretKey = import.meta.env.VITE_BZP_SECRET_KEY; 16. Troubleshooting 16.1 Styles are not applied Possible cause: The SDK stylesheet was not imported. Fix Ts import "@miden-npm/vue/dist/styles.css"; 16.2 transactionUpdate is not firing Possible causes: Event listener not attached Invalid payment object Invalid SDK key Network issues Fix Vue :secretKey="secretKey" :paymentObject="paymentObject" @transactionUpdate="handleTransactionUpdate" /> 16.3 Redirect is not working Possible causes: Missing redirect URL Invalid redirect URL HTTP redirect URL in production Fix Ts redirectUrl: "https://merchantapp.com/payment-success"; 16.4 Iframe is not loading Possible causes: Invalid environment Invalid SDK key Browser restrictions Parent domain restrictions Check your browser console for errors. 17. Full Example App.vue Vue <template> :secretKey="secretKey" :paymentObject="paymentObject" environment="sandbox" @transactionUpdate="handleTransactionUpdate" @emitMessage="handleMessage" /> </template> <script setup lang="ts"> import { BzpCheckoutCard } from "@miden-npm/vue"; interface PaymentObject { merchantName: string; amount: number; currency: string; email: string; phoneNumber: string; narration: string; redirectUrl: string; } interface TransactionUpdateEvent { status: "success" | "failed" | "pending"; reference?: string; message?: string; } interface SdkMessageEvent { state: "success" | "error" | "info" | "warning"; message: string; } const secretKey = "YOUR_SECRET_KEY"; const paymentObject: PaymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; const handleTransactionUpdate = ( event: TransactionUpdateEvent ) => { console.log("Transaction update:", event); if (event.status === "success" && event.reference) { verifyPayment(event.reference); } }; const handleMessage = ( event: SdkMessageEvent ) => { console.log(`[${event.state}] ${event.message}`); }; const verifyPayment = async (reference: string) => { console.log("Verify payment:", reference); // Send reference to backend }; </script> 18. Changelog Document SDK changes using semantic versioning. v1.0.0 Initial SDK release Added checkout button Added checkout card Added checkout iframe Added transaction events Added iframe support 19. Support For support, contact the development team or open an issue in the repository. When reporting issues, include: SDK version Vue version Browser Environment Error message Steps to reproduce
  • [React](https://docs.miden.co/payment-gateway/sdks/react.md): 1. Introduction The React Checkout SDK allows merchants to integrate secure payment checkout flows directly into React applications. The SDK supports multiple checkout experiences: Checkout Button Embedded Checkout Card Embedded Checkout Iframe The SDK is designed for: React 17+ Vite Create React App (CRA) Next.js TypeScript and JavaScript projects 2. Installation Install the SDK using your preferred package manager. npm ```bash npm install @miden-npm/react yarn Bash yarn add @miden-npm/react pnpm Bash pnpm add @miden-npm/react 3. Import Styles Import the SDK styles once at the root of your application. Vite / React main.tsx TSX import React from "react"; import ReactDOM from "react-dom/client"; import App from "./App"; import "@miden-npm/react/dist/styles.css"; ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render( <React.StrictMode> <App /> </React.StrictMode> ); JavaScript Version main.jsx JSX import React from "react"; import ReactDOM from "react-dom/client"; import App from "./App"; import "@miden-npm/react/dist/styles.css"; ReactDOM.createRoot(document.getElementById("root")).render( <React.StrictMode> <App /> </React.StrictMode> ); 4. Quick Start The example below shows how to render an embedded checkout card. App.tsx TSX import React from "react"; import { BzpCheckoutCard } from "@miden-npm/react"; const App = () => { const secretKey = "YOUR_SECRET_KEY"; const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order payment", redirectUrl: "https://merchantapp.com/payment-success", }; const onTransactionUpdate = (event: any) => { console.log("Transaction update:", event); if (event.status === "success") { // Verify payment on your backend } if (event.status === "failed") { // Handle failed payment } if (event.status === "pending") { // Handle pending payment } }; const onEmitMessage = (message: any) => { console.log("SDK message:", message); }; return ( secretKey={secretKey} paymentObject={paymentObject} environment="sandbox" onTransactionUpdate={onTransactionUpdate} onEmitMessage={onEmitMessage} /> ); }; export default App; 5. Configuration 5.1 Common Props These props are supported across all SDK components. Title Description Title Description Title Prop Type Required Default Description secretKey string Yes — Merchant SDK key paymentObject object Yes — Payment details object environment `"sandbox" "production"` No "sandbox" 6. Payment Object The paymentObject contains the transaction information required to initialize checkout. Example Ts const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; 6.1 Payment Object Fields Title Description Title Description Field Type Required Description merchantName string Yes Merchant display name amount number Yes Transaction amount currency string Yes Currency code, for example "NGN" email string Yes Customer email phoneNumber string Yes Customer phone number narration string Yes Payment description redirectUrl string Yes Redirect URL after payment 6.2 Recommended TypeScript Interface Ts export interface PaymentObject { merchantName: string; amount: number; currency: string; email: string; phoneNumber: string; narration: string; redirectUrl: string; } 7. Components 7.1 Checkout Button The checkout button component renders a button that launches checkout. It supports: Redirect checkout Iframe checkout Props Title Description Title Description Title Prop Type Required Default Description secretKey string Yes — Merchant SDK key paymentObject object Yes — Payment details mode `"redirect" "iframe"` No "redirect" environment `"sandbox" "production"` No "sandbox" Redirect Mode TSX import { BzpCheckoutButton } from "@miden-npm/react"; secretKey={secretKey} paymentObject={paymentObject} mode="redirect" environment="sandbox" />; Iframe Mode TSX import { BzpCheckoutButton } from "@miden-npm/react"; secretKey={secretKey} paymentObject={paymentObject} mode="iframe" environment="sandbox" />; Behavior Title Description Mode Description redirect Opens checkout on a new page iframe Opens checkout inside an iframe overlay 7.2 Checkout Card The checkout card component renders a fully embedded checkout form directly inside your application. Example TSX import { BzpCheckoutCard } from "@miden-npm/react"; secretKey={secretKey} paymentObject={paymentObject} environment="production" />; Description The checkout card allows merchants to embed payment fields directly inside their React application. The component handles: Card collection Payment initialization Payment status updates Secure checkout flow 7.3 Checkout Iframe The checkout iframe component embeds the checkout page directly into your application using an iframe. Example TSX import { BzpCheckoutIframe } from "@miden-npm/react"; secretKey={secretKey} paymentObject={paymentObject} environment="sandbox" />; Description The iframe component is useful when merchants want checkout embedded inline within a page. The component automatically handles: Secure iframe communication Dynamic resizing Transaction updates 8. Handling Responses The SDK provides multiple ways to receive transaction updates and SDK messages. 8.1 Transaction Updates All checkout components accept an onTransactionUpdate callback. This callback runs whenever the payment status changes. Example TSX secretKey={secretKey} paymentObject={paymentObject} onTransactionUpdate={(event) => { console.log("Transaction status:", event.status); if (event.status === "success") { // Handle successful payment } if (event.status === "failed") { // Handle failed payment } if (event.status === "pending") { // Handle pending payment } }} /> Example Transaction Payload JSON { "status": "success", "reference": "TXN_12345", "message": "Payment completed successfully" } Recommended TypeScript Interface Ts export interface TransactionUpdateEvent { status: "success" | "failed" | "pending"; reference?: string; message?: string; } 8.2 SDK Messages All checkout components accept an onEmitMessage callback. This callback can be used to display SDK notifications or feedback to users. Example TSX secretKey={secretKey} paymentObject={paymentObject} onEmitMessage={(msg) => { const { state, message } = msg; console.log(`[${state.toUpperCase()}]`, message); }} /> Example Message Payload JSON { "state": "success", "message": "Payment initialized successfully" } Recommended TypeScript Interface Ts export interface SdkMessageEvent { state: "success" | "error" | "info" | "warning"; message: string; } 9. Redirect Callback Handling If checkout uses redirect mode, the SDK redirects the customer to the redirectUrl specified in the paymentObject . Example Payment Object Ts const paymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; Example Success Page success.tsx TSX const urlParams = new URLSearchParams(window.location.search); const status = urlParams.get("status"); const reference = urlParams.get("reference"); if (status === "success" && reference) { // Verify payment on your backend } 10. Iframe Response Handling When checkout runs inside an iframe, your app can receive updates in two ways: Using the onTransactionUpdate callback Listening for browser postMessage events Using onTransactionUpdate TSX secretKey={secretKey} paymentObject={paymentObject} onTransactionUpdate={(event) => { console.log(event); }} /> Using postMessage Ts window.addEventListener("message", (event) => { if (event.data?.type === "transactionUpdate") { console.log("Transaction status:", event.data.status); console.log("Transaction reference:", event.data.reference); } }); Example postMessage Payload JSON { "type": "transactionUpdate", "status": "success", "reference": "TXN_12345", "message": "Payment completed successfully" } 11. Environment Configuration The SDK supports two environments. Title Description Value Description sandbox Testing environment production Live production environment Default Environment Ts sandbox Example TSX secretKey={secretKey} paymentObject={paymentObject} environment="production" /> 12. Next.js Usage If you are using Next.js App Router, mark the component file as a client component. Example TSX "use client"; import { BzpCheckoutCard } from "@miden-npm/react"; This SDK relies on browser APIs and must run on the client side. 13. Recommended Payment Verification Flow Do not fulfill orders based only on frontend payment events. Always verify successful payments on your backend. Recommended Flow Customer starts checkout SDK initializes payment Customer completes payment SDK returns transaction reference Frontend sends reference to backend Backend verifies transaction Backend confirms payment status Merchant fulfills the order Example Ts const onTransactionUpdate = async (event: any) => { if (event.status === "success" && event.reference) { await verifyPayment(event.reference); } }; const verifyPayment = async (reference: string) => { await fetch("/api/payments/verify", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ reference }), }); }; 14. Security Notes Follow these security best practices when integrating the SDK. Do not expose private server-side keys publicly Verify payments on your backend Use HTTPS redirect URLs in production Store production credentials securely Use environment variables for configuration Do not fulfill orders based only on frontend responses Environment Variable Example Vite Env VITE_BZP_SECRET_KEY=YOUR_SECRET_KEY React Usage Ts const secretKey = import.meta.env.VITE_BZP_SECRET_KEY; 15. Troubleshooting 15.1 Styles are not applied Possible cause: The SDK stylesheet was not imported. Fix Ts import "@miden-npm/react/dist/styles.css"; 15.2 onTransactionUpdate is not firing Possible causes: Callback not passed Invalid payment object Invalid SDK key Network issues Fix TSX secretKey={secretKey} paymentObject={paymentObject} onTransactionUpdate={(event) => { console.log(event); }} /> 15.3 Redirect is not working Possible causes: Missing redirect URL Invalid redirect URL HTTP redirect URL in production Fix Ts redirectUrl: "https://merchantapp.com/payment-success"; 15.4 Iframe is not loading Possible causes: Invalid environment Invalid SDK key Browser restrictions Parent domain restrictions Check your browser console for errors. 16. Full Example App.tsx TSX import React from "react"; import { BzpCheckoutCard } from "@miden-npm/react"; interface PaymentObject { merchantName: string; amount: number; currency: string; email: string; phoneNumber: string; narration: string; redirectUrl: string; } interface TransactionUpdateEvent { status: "success" | "failed" | "pending"; reference?: string; message?: string; } interface SdkMessageEvent { state: "success" | "error" | "info" | "warning"; message: string; } const App = () => { const secretKey = "YOUR_SECRET_KEY"; const paymentObject: PaymentObject = { merchantName: "Raymahni LLC", amount: 120, currency: "NGN", email: "customer@example.com", phoneNumber: "07026536637", narration: "Order #123", redirectUrl: "https://merchantapp.com/payment-success", }; const onTransactionUpdate = (event: TransactionUpdateEvent) => { console.log("Transaction update:", event); if (event.status === "success" && event.reference) { verifyPayment(event.reference); } }; const onEmitMessage = (event: SdkMessageEvent) => { console.log(`[${event.state}] ${event.message}`); }; const verifyPayment = async (reference: string) => { console.log("Verify payment:", reference); // Send reference to backend }; return ( secretKey={secretKey} paymentObject={paymentObject} environment="sandbox" onTransactionUpdate={onTransactionUpdate} onEmitMessage={onEmitMessage} /> ); }; export default App; 17. Changelog Document SDK changes using semantic versioning. v1.0.0 Initial SDK release Added checkout button Added checkout card Added checkout iframe Added transaction callbacks Added iframe support 18. Support For support, contact the development team or open an issue in the repository. When reporting issues, include: SDK version React version Browser Environment Error message Steps to reproduce
• [USD](https://docs.miden.co/business-accounts-1/usd.md): 1. Overview The USD Account system enables businesses and individuals to create, manage, and transact using USD accounts. The process involves application submission, account creation, beneficiary management, and various transaction capabilities. 2. Step-by-Step Process Step 1: Application Submission To open a USD account, the customer (business or individual) must submit an application. Endpoint for Businesses: This is used to create a business customer . Businesses must create a business profile through the system. Endpoint for Individuals: This is used to create an individual customer . Individuals must create an individual profile Retrieve Customer List: This is used to fetch a list of all customers Retrieve Specific Customer Details: This is used to fetch the details of a customer Step 2: Application Approval & Account Creation Once an application is approved, the customer can proceed to create a USD account. Create Account: A customer can create a USD account under their approved profile. Activate/Deactivate Account: Accounts can be activated or deactivated when needed. Retrieve All Accounts: A customer can retrieve a list of all their accounts. Retrieve Specific Account Details: A customer can view details of a specific account. Retrieve Account Statement: A customer can generate an account statement with filters like date range and account number. Step 3: Add Beneficiaries Before transacting, customers must add beneficiaries to their accounts. Add FIAT Beneficiary (NGN, USD, EUR): Customers can add FIAT beneficiaries (NGN, USD, EUR). Add Coin Beneficiary (Coming Soon): Step 4: Transactions Once a USD account is created and beneficiaries are added, customers can perform transactions. 4.1. Wallet Transfers (P2P Transactions) Customers can transfer funds between their wallets or to another user within the same system. 4.2. Coin Transfers (USDC, etc.) Customers can send USD and convert it to USDC via available payment rails. 4.3. NGN Transfers Customers can send USD and convert it to NGN, settling into a Nigerian bank account. 4.4. USD Transfers Customers can transfer USD directly to another USD account. 4.5. EUR Transfers Customers can transfer USD and convert it to EUR for international transactions. Step 5: Retrieve Transaction History Retrieve All Transactions: Customers can retrieve a list of all transactions for their accounts. Retrieve Specific Transaction Details: Detailed information about a specific transaction
  • [Customer Onboarding](https://docs.miden.co/business-accounts-1/usd/customer-onboarding.md): Overview: To access the full capabilities of the USD Account API and onboard your individual customers, you must first complete the Individual KYC (Know Your Customer) process. This process includes: Agreeing to our Terms of Service . Filling out the Individual KYC or business KYB form. Awaiting application approval. Once verified, you unlock the following features: Customer USD Accounts : Offer USD accounts to your individual customers (each must complete their KYC verification). USD Transactions : Fund your account with stablecoin or USD. Global Transfers : Transfer USD to USD, NGN, EUR, or stablecoin beneficiaries (USDC & USDT). Liquidation Address Generation : Create addresses for seamless coin transactions. External Account Integration : Attach individual fiat and crypto accounts to receive payments. Available APIs Create Individual Customer API : Initiate KYC for individual applicants and customers. Create Business Customer API : Initiate KYC for business applicants and customers. Get Customers API : Retrieve a list of verified customers. Get Customer API : Access detailed information about a specific verified customer. KYC Process The Customers API allows you to seamlessly submit KYC information for individual applicants. This ensures compliance and smooth onboarding through the following process: KYC Requirements for Customers Government ID : Mandatory for account creation, enabling elevated transaction limits. Individual Customers : Can submit their NIN (National Identification Number) under the taxIdentificationNumber field. Customer Creation Individual Customer Creation To create an individual customer, use the Create Individual Customer API . Mandatory : A valid proof_of_address_document is required. For all “Country” fields, submit the ISO 3166-1 alpha-3 country code . Business Customer Creation To create an individual customer, use the Create Business Customer API . KYC Status Review Process Once a customer is created, Miden reviews the submitted KYC information and provides a status update on the current state of verification: Automated Review : Completed in approximately 10 minutes. Manual Reviews : May extend to 1-2 business days . KYC Status Progression KYC Rejection Details In some cases, customers may transition directly from not_started to rejected , bypassing the under_review stage. This typically occurs when the tax identification number is invalid. When Miden encounters a verification issue, the status can shift immediately to rejected.
    • [Create Business Customer](https://docs.miden.co/business-accounts-1/usd/customer-onboarding/create-business-customer.md): Description Creates a new business customer account. This endpoint is used to onboard a business by capturing its company details, compliance information, address, source of funds questionnaire, beneficial ownership details, and supporting documents. Usage Use this endpoint when you need to: create a new business customer account onboard a corporate or registered business submit KYB and compliance information for a business register ultimate beneficial owners and supporting documents This is a business account creation operation . Notes Document fields must be sent as base64-encoded files using the data URI scheme . At least one beneficial owner with hasControl = true should be provided. title is required when a beneficial owner has control of the business. govIdCountry and address country fields must use three-letter ISO alpha-3 country codes such as NGA . High-risk activities should use the supported enum values defined for the API, such as money_services , third_party_payment_processing , and operate_foreign_exchange_virtual_currencies_brokerage_otc .
    • [Create Individual Customer](https://docs.miden.co/business-accounts-1/usd/customer-onboarding/create-individual-customer.md): Description Creates a new individual customer profile. This endpoint is used to onboard an individual customer by capturing personal information, address details, source-of-funds questionnaire data, identification details, and supporting KYC documents. Usage Use this endpoint when you need to: create a new individual customer account onboard an individual customer submit KYC information and supporting documents register an individual customer for USD business account services This is an individual customer creation operation . Notes Government ID and proof of address documents should be sent as base64-encoded files . govIdCountry and address.country must use three-letter ISO alpha-3 country codes such as NGA . mostRecentOccupation should contain a valid occupation code from the supported occupation list. Supported employmentStatus , expectedMonthlyPayments , primaryPurpose , and sourceOfFunds values should match the allowed enums defined for the API.
    • [Get Customer](https://docs.miden.co/business-accounts-1/usd/customer-onboarding/get-customer.md): Description Retrieves a customer profile by customer ID. This endpoint returns customer details, account status, customer type, capability status, rejection reasons, and terms of service acceptance status for either an individual or business customer. Usage Use this endpoint when you need to: retrieve an existing customer profile check whether a customer is individual or business confirm customer account status view enabled or pending account capabilities This is a customer retrieval operation . Notes The response structure may differ slightly depending on whether the customer is individual or business . Capability values may return as active , pending , or other configured status values. Use the type field to determine whether the customer profile is an individual or business account.
    • [Get Customers](https://docs.miden.co/business-accounts-1/usd/customer-onboarding/get-customers.md): Description Retrieves a list of customers on the system. This endpoint returns both individual and business customers , including their personal/business details, onboarding information, compliance data, and account status. Usage Use this endpoint when you need to: fetch all customers on your account filter customers by status (e.g., active) view onboarding and compliance details retrieve both individual and business customer records This is a customer listing operation with pagination support. Notes The data array may contain a mix of individual and business customers . Fields like firstName and lastName apply to individuals, while name applies to businesses. Some fields may return "null" depending on customer type or onboarding stage. Pagination fields ( currentPage , totalPages , etc.) should be used for large datasets.
  • [Accounts](https://docs.miden.co/business-accounts-1/usd/accounts.md): Description The Accounts APIs provide a complete set of endpoints for managing USD Accounts and related account operations within the Miden ecosystem. These APIs allow you to create, activate, deactivate, and retrieve account information for both fiat and crypto-enabled account structures. They support secure account management, balance visibility, transaction readiness, and multi-rail payment integration across supported financial products. With the Accounts API suite, you can seamlessly manage account lifecycles, monitor account activity, and enable USD and blockchain-based financial operations within your application. Requests Available Create USD Account Create a USD Account for storing and managing USD balances and supported digital assets. The account can receive deposits, support wallet transactions, and serve as the primary account structure for USD-based financial activity within the Miden ecosystem. Activate/Deactivate Account Enable or disable an existing account based on operational or compliance requirements. This endpoint helps control account accessibility, allowing you to temporarily restrict account usage, freeze inactive accounts, or reactivate previously disabled accounts. Get All Accounts Retrieve all accounts associated with your organization or customer profile. The response includes both active and inactive accounts, along with key details such as account type, status, balances, and unique account identifiers. Get Account Details Retrieve detailed information about a specific account. This includes account status, balances, supported currency or network information, and other metadata required for monitoring and account management operations.
    • [Create Account](https://docs.miden.co/business-accounts-1/usd/accounts/activate-deactivate-account-copy.md): Description Creates a USD account for a specific customer. This endpoint provisions a customer account that supports USD deposits and can also be funded through a supported blockchain network using a supported stablecoin. Usage Use this endpoint when you need to: create a USD account for a customer assign a blockchain funding address to the account enable USD and stablecoin-based funding retrieve bank deposit details linked to the account This is an account creation operation . Notes The account is created for a each customer, individual or business. The chain determines the blockchain network used for crypto funding. The address returned is used for funding the account through the selected blockchain network. The addressId may be used as the account ID when retrieving account details.
    • [Activate/Deactivate Account](https://docs.miden.co/business-accounts-1/usd/accounts/activate-deactivate-account.md): Description Activates or deactivates an existing customer account. This endpoint allows you to control whether a customer account is active and available for transactions or temporarily disabled from use. Usage Use this endpoint when you need to: activate a previously disabled account deactivate an active account restrict account activity for operational or compliance reasons restore account access after suspension or review This is an account status management operation . Notes Setting activate to true changes the account status to active . Setting activate to false changes the account status to inactive . Deactivated accounts may be restricted from performing transactions. The walletId uniquely identifies the customer account being updated.
    • [Get All Accounts](https://docs.miden.co/business-accounts-1/usd/accounts/activate-deactivate-account-copy-1.md): Description Retrieves a paginated list of all accounts across customers. This endpoint returns account details such as account status, supported currency, blockchain network, balances, and associated customer information. Usage Use this endpoint when you need to: retrieve all customer accounts monitor account statuses and balances filter accounts by customer or wallet ID retrieve account activity and collection statistics paginate large account datasets This is an account retrieval operation . Notes Results are returned in a paginated format. Use PageNumber and PageSize to navigate large datasets. walletStatus may return values such as active or inactive . virtualAccountId and virtualAccount may return null if no linked USD account exists. chain and network usually return the same blockchain value. Collection statistics include both count and total deposited volume.
    • [Get Account Details](https://docs.miden.co/business-accounts-1/usd/accounts/get-all-accounts-copy.md): Description Retrieves detailed information about a specific customer account. This endpoint returns the account status, supported funding currency, blockchain network, wallet address, balance, and attached USD bank account details. Usage Use this endpoint when you need to: retrieve details of a specific customer account check the account status and balance view the stablecoin funding address confirm the blockchain network linked to the account retrieve USD bank deposit information attached to the account This is an account details retrieval operation . Notes The accountId may correspond to the addressId returned when the account is created. The address is used to fund the account through the selected blockchain network. sourceBankInformation contains USD bank deposit details linked to the account. balance.availableAmount represents the amount currently available for use. lienAmount represents funds that are restricted or unavailable.
    • [Get Account Statement](https://docs.miden.co/business-accounts-1/usd/accounts/get-account-statement.md): Description Retrieves the transaction history for a specified USD Account within a given date range. This endpoint returns a detailed account statement containing all transactions posted to the account during the specified period. The statement includes transaction amounts, transaction types, running balances, references, narrations, statuses, and timestamps. It is useful for account reconciliation, auditing, transaction tracking, and financial reporting. Usage Use this endpoint when you need to: retrieve historical account transactions reconcile account balances generate account statements for reporting purposes verify transaction activity within a specific period track inflows, outflows, and account movements This is an account statement retrieval operation. Notes The statement includes all transactions posted within the specified date range. partTransactionType indicates transaction direction: D = Debit C = Credit runningBalance reflects the account balance immediately after each transaction is posted. Transactions are returned with both internal and external reference identifiers for reconciliation purposes. Reversed transactions can be identified using the isReversed field. valueDate may differ from transactionDate depending on settlement and posting timelines. The transactions array may be empty if no transactions exist within the specified date range. Use transactionReference when reconciling transactions with other account activities or webhook events.
  • [Beneficiaries](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries.md): Description The External Accounts APIs provide endpoints for creating and managing beneficiary accounts used for withdrawals and payouts from a Miden USD Account. These APIs allow users to save and manage fiat beneficiary accounts across supported currencies, making it easier to reuse payout destinations for future transfers and off-ramp operations. The folder includes APIs for adding beneficiary bank accounts, retrieving saved beneficiaries, and managing payout destinations for supported fiat currencies. Available Subfolders Fiat Accounts USD This section contains APIs for creating and managing USD beneficiary bank accounts used for payouts and transfers. NGN This section provides APIs for adding and managing Nigerian Naira (NGN) beneficiary bank accounts. These beneficiaries can be used for NGN payouts after converting USD balances into local currency. EUR This section contains APIs for creating and managing Euro-denominated beneficiary bank accounts for EUR payouts and settlements. Use Cases for External Accounts (Beneficiaries) Save Beneficiary Accounts Users can securely save frequently used bank accounts for future payouts and withdrawal operations. Manage Payout Destinations Users can retrieve and manage saved beneficiary accounts across supported fiat currencies such as USD, NGN, and EUR. Simplify Withdrawal Operations Saved beneficiaries help streamline payout workflows by reducing the need to repeatedly provide bank account details for future transfers.
    • [Fiat](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat.md): Description This subfolder contains APIs for creating and managing fiat bank account beneficiaries. These beneficiaries serve as recipient accounts that can receive funds from a user's USD Account. The Fiat folder currently supports three currencies: USD, NGN, and EUR , allowing users to save beneficiary bank accounts across supported regions for future transfers. Creating a beneficiary does not initiate a transfer. It simply stores the recipient's banking details so they can be selected when sending funds. Available Subfolders USD Beneficiaries Contains APIs for adding and managing U.S. dollar-denominated bank account beneficiaries. These beneficiaries can be used when sending funds to USD bank accounts through supported domestic or international payment rails. NGN Beneficiaries Contains APIs for adding and managing Nigerian Naira (NGN) bank account beneficiaries. These beneficiaries can be used when sending funds to Nigerian bank accounts in NGN. EUR Beneficiaries Contains APIs for adding and managing Euro-denominated bank account beneficiaries. These beneficiaries can be used when sending funds to bank accounts operating in EUR across supported regions. Use Cases Beneficiary Management Save recipient bank account details for future transfers without having to re-enter banking information each time a payment is initiated. Domestic and International Transfers Maintain beneficiary records across multiple currencies and regions, including USD, NGN, and EUR accounts. Faster Payment Initiation Pre-configured beneficiaries can be selected during transfer creation, simplifying the payment process and reducing data-entry errors. Multi-Currency Support Support payments to recipients across different banking jurisdictions by maintaining beneficiary accounts in multiple currencies. Notes Beneficiaries must be created before they can be selected as transfer recipients. The beneficiary currency should match the currency of the destination bank account. Creating a beneficiary only stores recipient details and does not move funds. Beneficiary details are validated before they are made available for transfers. Users can maintain multiple beneficiaries across supported currencies.
      • [USD](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat/usd.md): Overview The USD Beneficiaries folder contains APIs for creating and managing USD bank account beneficiaries. Beneficiaries are recipient bank accounts that can receive funds from a user's USD Account. These APIs allow users to save beneficiary details for future transfers, eliminating the need to re-enter banking information each time a transfer is initiated. The folder supports both business (corporate) and individual (personal) beneficiaries across domestic and international payment rails. Available Beneficiary Types 1. Corporate Beneficiaries (Business Accounts) Corporate beneficiaries are business-owned bank accounts that can receive USD transfers from a user's USD Account. Depending on the beneficiary's banking location and payment rail, one of the following beneficiary types should be used: Corporate US Used to add a USD business bank account domiciled in the United States. This beneficiary type is intended for corporate accounts operating within the US banking system and supporting domestic USD transfers. Corporate SWIFT Used to add a USD business bank account located outside the United States that receives funds through the SWIFT network. This beneficiary type is suitable for international corporate transfers where an IBAN is not required. Corporate SWIFT IBAN Used to add a USD business bank account that requires an IBAN (International Bank Account Number) for receiving SWIFT transfers. This beneficiary type is commonly used for business accounts in Europe, the Middle East, and other IBAN-supported regions. 2. Individual Beneficiaries (Personal Accounts) Individual beneficiaries are personal bank accounts that can receive USD transfers from a user's USD Account. Individual US Used to add a personal USD bank account domiciled in the United States. This beneficiary type is intended for transfers to individuals through domestic US payment rails. When to Use Each Beneficiary Type Beneficiary Type Use Case Corporate US Business beneficiary located in the United States. Corporate SWIFT Business beneficiary located outside the United States that receives funds via the SWIFT network. Corporate SWIFT IBAN Business beneficiary that requires an IBAN for SWIFT transfers. Individual US Personal beneficiary located in the United States. Notes Beneficiaries must be created before they can be used as transfer recipients. The beneficiary type selected should match the beneficiary's account ownership (business or individual) and banking requirements. International beneficiaries may require additional banking information such as SWIFT codes or IBANs. Beneficiary details are validated before they can be used for transfers. Creating a beneficiary does not initiate a transfer; it only saves the recipient account for future use.
        • [Corporate (US)](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat/usd/corporate-us.md): Description Creates a corporate USD beneficiary domiciled in the United States. This endpoint allows users to add a U.S.-based business bank account as a beneficiary for future USD transfers. Once created, the beneficiary can be selected as a recipient when initiating payments from a USD Account. The beneficiary must be a business-owned account operating within the U.S. banking system and capable of receiving ACH or Fedwire transfers. Usage Use this endpoint when you need to: add a U.S.-based corporate beneficiary save business banking details for future USD transfers create a beneficiary that receives funds through ACH or Fedwire manage recipient business accounts for payment operations This is a beneficiary creation operation and does not initiate a transfer. Notes This endpoint supports only U.S.-based corporate USD beneficiaries. The routing number must be valid for ACH or Fedwire processing. The beneficiary address should match the details associated with the beneficiary account. accountOwnerType must be business . accountType must be us . Creating a beneficiary does not move funds or initiate a payment. The returned externalAccountId should be stored and used when referencing the beneficiary in future transfer requests.
        • [Corporate (Swift)](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat/usd/corporate-swift.md): Description Creates a corporate USD beneficiary that receives funds through the SWIFT network. This endpoint allows users to add a non-U.S. business bank account as a beneficiary for future USD transfers. It is intended for corporate beneficiaries whose banks support SWIFT transactions and do not require an IBAN. Once created, the beneficiary can be selected as a recipient when initiating international USD transfers from a USD Account. Usage Use this endpoint when you need to: add an international corporate beneficiary save business banking details for future SWIFT transfers create a beneficiary located outside the United States manage international business recipients for USD payments This beneficiary type should be used for countries where an IBAN is not required. For beneficiaries in IBAN-supported jurisdictions, use the Corporate (SWIFT IBAN) Beneficiary endpoint instead. This is a beneficiary creation operation and does not initiate a transfer. Notes This endpoint is intended for corporate beneficiaries receiving funds through the SWIFT network. accountType must be set to swift . accountOwnerType must be set to business . A valid SWIFT/BIC code is required. Beneficiary details should match the information held by the receiving bank. For beneficiaries in countries that require an IBAN, use the Corporate (SWIFT IBAN) Beneficiary endpoint. Creating a beneficiary does not move funds or initiate a transfer. Store the returned externalAccountId for use in future transfer requests.
        • [Individual (US)](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat/usd/individual-us.md): Description Creates an individual USD beneficiary domiciled in the United States. This endpoint allows users to add a personal U.S. bank account as a beneficiary for future USD transfers. Once created, the beneficiary can be selected as a recipient when initiating payments from a USD Account. The beneficiary must be an individual-owned account operating within the U.S. banking system and capable of receiving ACH or Fedwire transfers. Usage Use this endpoint when you need to: add a personal U.S. beneficiary save individual banking details for future USD transfers create a beneficiary that receives funds through ACH or Fedwire manage personal recipients for payment operations This is a beneficiary creation operation and does not initiate a transfer. Notes This endpoint supports only individual USD beneficiaries domiciled in the United States. The routing number must be valid for ACH or Fedwire processing. The beneficiary address should match the details associated with the beneficiary account. accountOwnerType must be individual . accountType must be us . Creating a beneficiary does not move funds or initiate a transfer. The returned externalAccountId should be stored and used when referencing the beneficiary in future transfer requests.
      • [NGN](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat/ngn.md): Description The NGN Beneficiaries subfolder contains APIs for creating and managing Nigerian Naira (NGN) bank account beneficiaries. These beneficiaries serve as recipient accounts that can receive NGN transfers from a user's USD Account. Once created, a beneficiary can be selected when initiating transfers to Nigerian bank accounts. The folder is designed for users who need to maintain beneficiary records for recipients within the Nigerian banking ecosystem, enabling faster and more efficient payment processing. Available APIs NGN Beneficiaries This section contains APIs for adding and managing Nigerian Naira (NGN) beneficiary accounts. Beneficiaries created through these APIs can be used as recipients for future NGN transfers to supported Nigerian banks. Use Cases Beneficiary Management Save Nigerian bank account details for future transfers without repeatedly entering recipient information. Local Currency Transfers Maintain beneficiary records for recipients who receive funds in Nigerian Naira (NGN). Faster Payment Processing Pre-configured beneficiaries can be selected during transfer creation, reducing manual entry and operational errors. Recipient Directory Management Create and manage multiple NGN beneficiaries for individuals, businesses, vendors, employees, or other payment recipients. Key Notes Beneficiaries must be created before they can be selected as transfer recipients. Creating a beneficiary does not initiate a transfer or move funds. Beneficiary details are validated before they become available for transfers. Users can maintain multiple NGN beneficiaries under a single account. Beneficiaries can be used for future NGN payout and transfer operations supported by the platform.
        • [Add Account](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat/ngn/add-account.md): Description The Add NGN Beneficiary Account API allows users to create and manage Nigerian Naira (NGN) beneficiary bank accounts that can be used as recipients for future transfers. This endpoint supports both individual and business beneficiaries and enables users to save Nigerian bank account details for repeated use. Once created, the beneficiary can be selected when initiating NGN transfers from a USD Account. Usage To add an NGN beneficiary, send a POST request to this endpoint with the beneficiary's bank account details, including the account number, bank code, account owner information, and account type. Upon successful creation, the API returns an externalAccountId that uniquely identifies the beneficiary account and can be used in future transfer operations.
      • [EUR](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat/eur.md): Description The EUR Beneficiary Accounts subfolder provides APIs for creating and managing Euro (EUR) beneficiary bank accounts. These beneficiary accounts can be used as recipients for future transfers, allowing users to send funds to Euro-denominated bank accounts across supported regions. The APIs support the creation and maintenance of EUR beneficiaries, making it easier to store recipient details and reuse them for subsequent transactions. This subfolder supports both SWIFT and SWIFT IBAN beneficiary types, ensuring compatibility with international banking requirements and European banking standards. Available Subfolders SWIFT This section contains APIs for creating EUR beneficiaries that receive funds through the SWIFT network without requiring an IBAN. These beneficiaries are typically used in countries and regions where SWIFT transfers are supported and IBAN is not mandatory. SWIFT IBAN This section contains APIs for creating EUR beneficiaries that require an International Bank Account Number (IBAN). This is commonly used across the European Economic Area (EEA) and other jurisdictions where IBAN is required for processing international transfers. Use Cases Save EUR Beneficiaries Create and store Euro-denominated beneficiary accounts for future transfers without re-entering banking details each time. International Transfers Manage beneficiaries that receive funds through the SWIFT network, supporting cross-border transactions across multiple countries. European Banking Support Add beneficiaries that require IBAN details for compliance with European banking standards and payment processing requirements. Reusable Recipient Management Maintain a centralized list of EUR beneficiaries that can be selected and reused whenever a transfer is initiated. Notes EUR beneficiaries are recipients only and do not initiate transfers themselves. The appropriate beneficiary type should be selected based on the recipient bank's requirements. Use the SWIFT endpoints when the beneficiary bank does not require an IBAN. Use the SWIFT IBAN endpoints when the beneficiary bank requires an IBAN for processing transfers. Beneficiary details are validated before becoming available for use in future transfer operations. Creating a beneficiary does not move funds or initiate a transfer.
        • [Corporate Swift Iban](https://docs.miden.co/business-accounts-1/usd/exterb-nal-accounts-beneficiaries/fiat/eur/corporate-swift-iban.md): Description The Corporate SWIFT IBAN Beneficiary API allows users to add a corporate EUR bank account that requires an IBAN (International Bank Account Number) as a beneficiary for future transfers. This endpoint is designed for businesses operating in countries where IBAN is mandatory for receiving international payments, particularly across Europe and other IBAN-compliant regions. Once created, the beneficiary can be selected as a recipient for future EUR transfers. Usage Use this endpoint when adding a corporate beneficiary whose bank account requires both an IBAN and a SWIFT/BIC code for international transfers. To create a beneficiary, submit the required business, banking, and address information. Upon successful creation, the beneficiary will be stored and made available for future transfer operations. Notes This endpoint is intended for corporate EUR beneficiaries that require an IBAN. The account.accountNumber field should contain the beneficiary's IBAN. A valid SWIFT/BIC code is required for international payment routing. The accountType must be set to swiftiban . The accountOwnerType must be set to business . Beneficiary creation only stores recipient details and does not initiate a transfer. Once created, the beneficiary can be reused for future EUR transfer transactions.
  • [Network Transfer](https://docs.miden.co/business-accounts-1/usd/transfers/network-transfer.md): Description Initiates an external network transfer from a customer wallet to a supported blockchain address. This endpoint allows users to send supported digital assets, such as USDC, from a USD Account wallet to an external wallet address on a selected blockchain network. The transfer request includes the source wallet, destination currency, payment rail, recipient wallet address, transfer amount, and optional developer fee. Usage Use this endpoint when you need to: transfer funds from a customer wallet to an external blockchain address send USDC through a supported network such as Ethereum, Polygon, Base, Arbitrum, Avalanche, Optimism, Solana, or Stellar initiate an on-chain payout from a wallet balance apply a fixed developer fee to the transaction This is a network transfer operation. Notes The clientDeveloperFee is a fixed amount, not a percentage. The finalAmount is calculated after fees are deducted from the initialAmount . The status field should be used to track the transfer lifecycle after initiation. Supported payment rails may include ethereum , polygon , base , arbitrum , avalanche , optimism , solana , and stellar . Ensure the destination wallet address matches the selected paymentRail . Submitting this request initiates the transfer process; final processing may depend on review, network confirmation, and payment rail settlement.
  • [Bank Transfer NGN](https://docs.miden.co/business-accounts-1/usd/transfers/bank-transfer-ngn.md): Description Initiates an external bank transfer to a saved NGN beneficiary account. This endpoint allows users to transfer funds from a source wallet to a Nigerian bank account beneficiary using the NIP payment rail. The destination account must already exist as an NGN beneficiary before this transfer can be initiated. The externalAccountId provided in the request represents the unique identifier of the saved NGN beneficiary account. Usage Use this endpoint when you need to: transfer funds to a saved NGN beneficiary send funds to a Nigerian bank account through NIP initiate an NGN payout from a customer wallet apply a fixed developer fee to the transaction This is a bank transfer to NGN beneficiary operation. Notes The NGN beneficiary must be created before initiating this transfer. The externalAccountId is the unique identifier of the saved NGN beneficiary. For NGN transfers, the paymentRail should be nip . The clientDeveloperFee is a fixed amount and not a percentage. The status field should be used to track the transfer lifecycle after initiation. Submitting this request creates a transfer request; final settlement may depend on processing, review, and payment rail completion.
  • [Bank Transfer USD](https://docs.miden.co/business-accounts-1/usd/transfers/bank-transfer-usd.md): Description Initiates an external USD bank transfer from a customer wallet to a saved USD beneficiary account. This endpoint allows users to transfer funds from a USD Account wallet to an external USD bank account that has previously been added as a beneficiary. The transfer is processed using a supported banking rail such as ACH. The destination account must first be created as a USD beneficiary. The externalAccountId provided in the request identifies the saved beneficiary that will receive the transfer. Usage Use this endpoint when you need to: transfer funds from a USD Account wallet to a bank account send funds to a previously saved USD beneficiary initiate ACH payouts from a customer wallet apply a fixed developer fee to the transaction This is a bank transfer to a USD beneficiary operation. Notes The destination account must already exist as a saved USD beneficiary. The externalAccountId represents the unique identifier of the beneficiary account receiving the transfer. The paymentRail determines how the transfer is processed. Common options include ach and ach_same_day . The clientDeveloperFee is a fixed amount and not a percentage. The status field should be used to track the transfer lifecycle after initiation. Submitting this request initiates the transfer process; settlement timing depends on the selected payment rail and processing status.
  • [Bank Transfer EUR](https://docs.miden.co/business-accounts-1/usd/transfers/bank-transfer-eur.md): Description Initiates an external EUR bank transfer from a customer wallet to a saved EUR beneficiary account. This endpoint allows users to transfer funds from a USD Account wallet to an external EUR bank account that has previously been added as a beneficiary. The transfer is processed using the SEPA payment rail and enables users to send funds to bank accounts across supported European regions. The destination account must first be created as a EUR beneficiary. The externalAccountId provided in the request identifies the saved beneficiary that will receive the transfer. Usage Use this endpoint when you need to: transfer funds from a USD Account wallet to a EUR bank account send funds to a previously saved EUR beneficiary initiate SEPA payouts from a customer wallet convert and transfer funds to beneficiaries in EUR apply a fixed developer fee to the transaction This is a bank transfer to a EUR beneficiary operation.
  • [All Transactions](https://docs.miden.co/business-accounts-1/usd/transfers/all-transactions.md): Description The Get All Transactions endpoint retrieves a paginated list of transactions associated with the authenticated account. It supports optional filtering by transaction ID, customer ID, currency, destination currency, client reference, and date range. This endpoint provides visibility into all transaction activities, including deposits, wallet top-ups, network transfers, bank transfers, and conversions. Usage Send a GET request to this endpoint to retrieve transaction records. Optional query parameters can be supplied to narrow the results returned. The response includes transaction details, pagination metadata, and status information for each transaction. Notes Results are returned in a paginated format. Filters can be combined to narrow transaction searches. Date filters should be provided in YYYY-MM-DD format. The endpoint returns both completed and in-progress transactions. Transaction records may include blockchain, bank transfer, wallet funding, conversion, and payout activities. Fields such as sourceAddress , destinationAddress , sourceTransactionHash , and payment rails may return null when not applicable to the transaction type.
  • [Transaction Details](https://docs.miden.co/business-accounts-1/usd/transfers/transaction-details.md): Description The Transaction Details endpoint retrieves detailed information about a specific transaction. This endpoint provides a complete breakdown of the transaction, including source and destination information, fees charged, transaction amounts, timestamps, status, and reference identifiers. Usage Send a GET request to this endpoint using the customerId and transactionId path parameters. The endpoint returns the complete details of the specified transaction, allowing users to track transaction status, review fees, and reconcile transaction records. Notes This endpoint returns information for a single transaction only. The clientReferenceId can be used to reconcile transactions with external systems. The receipt object provides a complete fee and settlement breakdown for the transaction. Depending on the transaction type, the source and destination objects may contain additional information such as wallet identifiers, bank account references, payment rails, or blockchain addresses. Timestamp values are returned in UTC format.
  • [Simulations](https://docs.miden.co/business-accounts-1/usd/simulations.md): Description The Simulation folder contains endpoints designed to emulate key financial and identity events within the system for testing or demonstration purposes. These endpoints allow developers to trigger mock events without performing real transactions or KYC verifications — enabling end-to-end testing of integration workflows in a sandbox environment. Available Endpoints Simulate Customer KYC Event Triggers a mock KYC (Know Your Customer) verification event for a test user. Useful for testing onboarding or compliance-related flows. Simulate Account Inflow Simulates an incoming transaction to a customer’s account. Simulate Stablecoin Inflow Simulates a deposit or transfer of stablecoins into an account, enabling the testing of crypto-related inflow scenarios. Use Case Use these endpoints in development or staging environments to validate how your application responds to key financial and compliance events before going live.
    • [Customer KYC Event](https://docs.miden.co/business-accounts-1/usd/simulations/customer-kyc-event.md): Description This endpoint allows you to simulate a Customer Know Your Customer (KYC) verification event in the sandbox environment. It is intended for testing onboarding and compliance workflows by updating a customer's KYC status without performing an actual verification. Usage Use this endpoint during development or testing to simulate different KYC outcomes for an existing customer. Supported Status Values Status Description NotStarted KYC process has not been initiated. AwaitingQuestionnaire Customer is required to complete the KYC questionnaire. Pending KYC submission has been received and is awaiting processing. Incomplete Required KYC information or documents are incomplete. UnderReview KYC submission is under compliance review. Rejected Customer failed KYC verification. Approved Customer successfully passed KYC verification. Notes This endpoint is available for sandbox/testing environments only and does not perform a real KYC verification. The customerId must belong to an existing test customer. Updating the KYC status triggers the same downstream workflows and webhooks that would occur during a real KYC event. Use only one of the supported status values when simulating a KYC event.
    • [Account Inflow](https://docs.miden.co/business-accounts-1/usd/simulations/account-inflow.md): Description This endpoint allows you to simulate an incoming account inflow event in the sandbox environment. It is used to test how your integration handles virtual account funding events across different deposit stages without processing a real transaction. Usage Use this endpoint during development or testing to simulate account inflow events for a customer’s virtual account. For the first inflow simulation, use the FundsReceived status and leave depositId empty or excluded. The response returns a depositId , which can then be used to simulate subsequent statuses such as PaymentSubmitted and PaymentProcessed . Supported Status Values Status Description FundsReceived Simulates that funds have been received into the virtual account. PaymentSubmitted Simulates that the received payment has been submitted for processing. PaymentProcessed Simulates that the payment has been processed successfully. Notes This endpoint is available for sandbox/testing environments only and does not process a real inflow. For FundsReceived , depositId should be left empty or excluded from the request. Use the depositId returned in the FundsReceived response to simulate the next stages of the same inflow. Supported statuses are FundsReceived , PaymentSubmitted , and PaymentProcessed . The virtualAccountId and customerId must belong to existing test records in the sandbox environment.
    • [Stablecoin Inflow](https://docs.miden.co/business-accounts-1/usd/simulations/stablecoin-inflow.md): Description This endpoint allows you to simulate a stablecoin deposit event in the sandbox environment. It is intended for testing crypto funding workflows by emulating the lifecycle of a stablecoin deposit without broadcasting a real blockchain transaction. Usage Use this endpoint during development or testing to simulate stablecoin inflow events into a customer's wallet. For the first simulation, use the FundsReceived status and leave depositTransactionHash and fromAddress empty or excluded. The response returns both values, which should then be supplied when simulating subsequent statuses such as PaymentSubmitted and PaymentProcessed . Supported Status Values Status Description FundsReceived Simulates that the stablecoin deposit has been detected. PaymentSubmitted Simulates that the deposit has been submitted for processing. PaymentProcessed Simulates that the deposit has been processed successfully. Notes This endpoint is available for sandbox/testing environments only and does not create a real blockchain transaction. For FundsReceived , depositTransactionHash and fromAddress should be left empty or omitted from the request. Use the depositTransactionHash and fromAddress returned from the initial simulation when simulating PaymentSubmitted or PaymentProcessed . Supported statuses are FundsReceived , PaymentSubmitted , and PaymentProcessed . The specified walletId and customerId must belong to existing test records in the sandbox environment.
• [NGN](https://docs.miden.co/business-accounts-1/ngn.md): Introduction to Miden NGN Virtual Account This folder provides you with a complete suite of APIs to facilitate seamless financial operations in Nigerian Naira (NGN). Designed for businesses operating within Nigeria, these APIs allow you to create and manage virtual NGN accounts for collections and perform efficient payouts to beneficiaries. Whether you're a corporate entity or an individual business owner, the NGN folder empowers you to streamline your local financial activities with precision and ease. Available Subfolders 1. Accounts The Accounts subfolder equips you with APIs to create and manage NGN virtual accounts tailored for collections. These accounts, available for both individuals and businesses, allow you to receive payments directly into a secure and unique NGN account. The features in this subfolder include: Create Static Account: Individual Allows you to create a static virtual NGN account linked to an individual customer for long-term use. Create Static Account: Business Provides APIs for creating static virtual NGN accounts designed specifically for corporate or business customers. Create Dynamic Account Generate dynamic NGN virtual accounts for one-time or short-term collections, ideal for transactional purposes. Re-assign Virtual Account Enables you to reassign an existing virtual account to a different customer or entity, optimizing account utilization. All Virtual Accounts Retrieve details of all NGN virtual accounts linked to your organization for easy management and oversight. Collection History Access a detailed record of all collections made through NGN virtual accounts, ensuring transparency and easy tracking of funds. 2. Payouts The Payouts subfolder provides you with the tools to disburse funds from your NGN wallet to beneficiaries within Nigeria. These APIs make local payments swift, secure, and reliable. The features in this subfolder include: Get Banks Retrieve a comprehensive list of Nigerian banks to enable seamless beneficiary setup for payouts. Name Inquiry Verify the account name of a beneficiary before initiating a bank transfer to ensure accuracy. Get Payout Charge Access information on charges applicable for NGN payouts, helping you plan your transactions effectively. Bank Transfer Perform secure transfers from your NGN wallet to your beneficiaries' local bank accounts. Transfer History View a detailed history of all bank transfers, allowing you to maintain an accurate record of payouts. Transaction Status Inquiry Check the status of a specific transaction to confirm its completion or address any issues promptly. Use Cases for the NGN Folder Local Collections: Create static or dynamic NGN virtual accounts to streamline your payment collection process from customers in Nigeria. Optimized Payment Operations: Perform secure and efficient payouts to your beneficiaries' local bank accounts with real-time verification. Account Management Flexibility: Manage, reassign, and track all your NGN virtual accounts effortlessly to ensure operational efficiency. Transparent Financial Reporting: Access detailed transaction histories for both collections and payouts, helping you maintain financial clarity.
  • [Collections](https://docs.miden.co/business-accounts-1/ngn/collections.md): Description This folder is designed to help you create, manage, and optimize NGN virtual accounts to support seamless collections for your business. Whether you need a static account for recurring payments or a dynamic one for one-time transactions, these APIs offer flexibility and efficiency. With these APIs, you can: Onboard new customers with dedicated virtual accounts. Manage account reassignments to optimize resource usage. Track collection performance and ensure financial transparency. Available APIs Create Static Account: Individual Use Case: Generate a dedicated virtual NGN account for individual customers. Best For: Long-term customer associations with consistent account details. Create Static Account: Business Use Case: Set up a fixed NGN account for businesses or corporate entities. Best For: Companies that require a permanent payment destination. Create Dynamic Account Use Case: Generate a temporary virtual NGN account for one-time transactions. Best For: Ad-hoc payments without long-term account assignments. Re-assign Virtual Account (if your bank is "Globus", ignore this endpoint) Use Case: Reassign an existing virtual NGN account to a different customer or entity. Best For: Optimizing virtual account usage and managing ownership changes. All Virtual Accounts Use Case: Retrieve a list of all virtual accounts linked to your organization. Best For: Gaining visibility & control over account operations. Collection History Use Case: View a record of all funds collected through your NGN virtual accounts. Best For: Financial reporting & transparency in collections. Why Use the Collection Folder? Title Description Feature Benefit Personalized Account Setup Create static or dynamic accounts tailored to your business model. Operational Efficiency Reassign accounts as needed to maximize virtual account resources. Comprehensive Tracking Get full visibility into active and historical virtual accounts. Conceptual Diagram
    • [Create Static Virtual Account: Individual](https://docs.miden.co/business-accounts-1/ngn/collections/create-static-virtual-account-individual.md): Overview This webhook is triggered whenever a collection is successfully received through a NGN Virtual Account . It provides detailed transaction information including the sender’s account details, transaction references, settlement amount, narration, and processing status. Usage Used to notify merchant systems in real time when funds are received into a NGN virtual account. This allows businesses to automatically reconcile payments, update customer balances, confirm deposits, and trigger downstream workflows. Event Type collection.virtual-accounts Event Class Collections Expected Behaviour When this webhook is received: Validate eventType Identify the receiving virtual account using virtualAccountNumber Confirm transaction success using status Match payment using merchantReference or transactionReference Record payer information from sourceAccountName and sourceAccountNumber Reconcile settlement using SettledAmount Update merchant/customer balances Trigger payment confirmation workflows Store narration and references for audit purposes Ensure idempotent processing using eventId Notes This webhook applies specifically to NGN virtual account collections transactionAmount represents the full customer payment SettledAmount represents the amount credited after deductions merchantReference should be used for merchant-side reconciliation transactionReference is the platform-generated tracking reference sourceAccountNumber and sourceAccountName identify the payer Always process duplicate webhook retries safely using eventId channel remains VirtualAccount for virtual account collections
    • [Create Static Virtual Account: Business](https://docs.miden.co/business-accounts-1/ngn/collections/create-static-virtual-account-individual-copy-3.md): Description This API allows businesses to create a static virtual account for a corporate entity. The generated account remains permanently linked to the business profile and can be used to receive NGN collections and other business payments. Usage Use this endpoint to generate a dedicated virtual account for a business using the organization’s registration and verification details. The created account can be reused for ongoing collections and settlement operations. This endpoint also supports preferred bank selection during account creation. Notes The bank field is optional. If no bank is supplied, Miden automatically assigns an available bank. Supported banks currently include: Globus Bank Providus Bank The generated account is static and can receive multiple collections over time. Static virtual accounts are ideal for recurring business collections and payment reconciliation.
    • [Create Dynamic Virtual Account](https://docs.miden.co/business-accounts-1/ngn/collections/create-static-virtual-account-business-copy.md): Description This API allows businesses to create dynamic virtual accounts for both individuals and corporate entities. Dynamic virtual accounts are temporary accounts commonly used for one-time or short-term payment collections. These accounts are ideal for transactions that require isolated payment tracking and simplified reconciliation. Usage Use this endpoint to generate a temporary virtual account for a customer or business transaction. Dynamic virtual accounts can be created for: Individuals — for personal or customer-specific collections. Businesses — for temporary or transaction-based corporate collections. The endpoint also supports preferred bank selection during account creation. Notes The bank field is optional. If no bank is supplied, Miden automatically assigns an available bank. Supported banks currently include: Globus Bank Providus Bank Dynamic virtual accounts are temporary and are primarily intended for transaction-specific collections. Dynamic accounts help simplify reconciliation by isolating payments to dedicated account numbers.
    • [All Virtual Accounts](https://docs.miden.co/business-accounts-1/ngn/collections/create-dynamic-virtual-account-copy.md): Description This endpoint retrieves all virtual accounts associated with the authenticated organization or account. The response includes account details, account status, collection statistics, provider information, and metadata related to each virtual account. Usage Use this endpoint to: Retrieve all created virtual accounts. Monitor account activity and collection statistics. Access account metadata for reconciliation and reporting. Track account status and account type information. Notes Both static and dynamic virtual accounts are returned in the response. Collection statistics are updated based on transactions processed on each account. Nullable fields may return "null" when no data exists. Results are paginated using currentPage , pageSize , and totalPages .
    • [Collection History](https://docs.miden.co/business-accounts-1/ngn/collections/collection-history.md): Description This endpoint allows you to retrieve NGN virtual account collection transactions within a specified date range. It returns collections received into reserved/virtual accounts, including the virtual account number, transaction amount, settled amount, source account details, transaction reference, provider, and pagination information. Usage Use this endpoint to view or reconcile NGN virtual account collections for a selected period. Pass startDate and endDate as query parameters in YYYY-MM-DD format. Notes Both startDate and endDate are required and must be provided in YYYY-MM-DD format. The endpoint returns collection transactions received into your NGN virtual accounts within the specified date range. Results are returned in a paginated format. Use currentPage , pageSize , totalCount , and totalPages to navigate through multiple pages of results. Depending on the payment provider or transaction channel, some fields (such as sourceBankName , status , transactionType , currency , ipAddress , and uniqueKey ) may be returned as null . Collection history is intended for reconciliation, reporting, and transaction tracking purposes.
  • [Payout](https://docs.miden.co/business-accounts-1/ngn/payout.md): Description The Payout Folder provides APIs that enable seamless bank transfers, transaction status checks, and charge calculations for efficient fund disbursements . Whether you’re verifying account details, checking fees, or tracking payouts, these APIs ensure smooth and secure transactions. With these APIs, you can: Retrieve bank details to enable transfers. Verify recipient account names before initiating payments. Calculate transfer fees before processing payouts. Perform bank transfers securely. Track past transactions with detailed history. Check real-time transaction status to confirm payment success. Available APIs Get Bank Use Case: Retrieve a list of supported banks and their respective bank codes. Best For: Populating bank selection fields when making transfers. Name Inquiry Use Case: Verify a recipient's account name before initiating a transfer. Best For: Ensuring funds are sent to the correct recipient. Get Payout Charge Use Case: Retrieve applicable transfer fees before processing a payout. Best For: Displaying fees to users before confirming transactions. Bank Transfer Use Case: Transfer funds from your business account to any NGN bank account. Best For: Disbursing payments to customers, vendors, or employees. Transfer History Use Case: Retrieve a list of past transfers with details such as status, amount, and recipient. Best For: Tracking payouts for audit & reconciliation. Transaction Status Inquiry Use Case: Check the real-time status of a previously initiated transfer. Best For: Confirming whether a payout succeeded, failed, or is pending. Why Use the Payout Folder? Title Description Feature Benefit Bank Verification Retrieve supported banks to ensure seamless transactions. Recipient Validation Prevent errors by confirming account names before sending funds. Transparent Charges Show users payout fees before processing transactions. Secure Transfers Initiate NGN bank transfers with real-time tracking. Transaction Monitoring Check transfer history and real-time transaction statuses. Conceptual Diagram Plain text +------------------+ | Get Bank | (Retrieve supported banks) +------------------+ +------------------+ | Name Inquiry | (Verify recipient details) +------------------+ +--------------------------------+ | Get Payout Charge | (Check transfer fees) +--------------------------------+ +-------------------+ +--------------------------+ | Bank Transfer | | Transaction Status Check | (Monitor transfer) +-------------------+ +--------------------------+ +----------------------------------+ | Transfer History | (View past transfers) +----------------------------------+ +------------------+ | Get Bank | (Retrieve supported banks) +------------------+ +------------------+ | Name Inquiry | (Verify recipient details) +------------------+ +--------------------------------+ | Get Payout Charge | (Check transfer fees) +--------------------------------+ +-------------------+ +--------------------------+ | Bank Transfer | | Transaction Status Check | (Monitor transfer) +-------------------+ +--------------------------+ +----------------------------------+ | Transfer History | (View past transfers) +----------------------------------+ Note: Each API is independent —they don’t have to be called in sequence. Some APIs are used before transfers (e.g., Get Bank, Name Inquiry, Get Payout Charge ). Others track and monitor payouts (e.g., Transfer History, Transaction Status Inquiry ). Bank Transfer is a key action , but it’s not mandatory for using the other endpoints.
    • [Get Banks](https://docs.miden.co/business-accounts-1/ngn/payout/all-virtual-accounts-copy-1.md): Description This endpoint retrieves the list of supported banks available for payouts and transfers. The response includes each bank’s name and NIP bank code required for transaction processing. Usage Use this endpoint to: Retrieve supported Nigerian banks for payouts. Populate bank selection dropdowns in applications. Obtain NIP bank codes required for transfers and account validation. Support bank account-related operations during payout processing. Notes The bank query parameter is optional. Returned banks may vary depending on the selected provider. nipBankCode should be used when initiating payouts or validating beneficiary accounts.
    • [Name Inquiry](https://docs.miden.co/business-accounts-1/ngn/payout/get-banks-copy.md): Description This endpoint validates a bank account before initiating a payout. By supplying the account number and bank code, the API retrieves the registered account name associated with the account. Usage Use this endpoint to: Verify beneficiary account details before processing payouts. Confirm that an account number belongs to the intended recipient. Reduce failed or misdirected transfers. Retrieve account holder information for payout validation. Notes accountNumber and bankCode are required query parameters. bank is optional and may be used to specify a provider. A successful name inquiry does not initiate a payout. Ensure the correct bankCode is supplied for accurate validation.
    • [Fetch Payout Charge](https://docs.miden.co/business-accounts-1/ngn/payout/fetch-payout-charge.md): Description This endpoint allows you to calculate the charge applicable to an NGN payout before initiating the payout. It returns the payout fee based on the payout amount provided. Usage Use this endpoint to confirm the payout charge for a specific payout amount before proceeding with the payout transaction. Notes This endpoint only calculates the applicable payout fee; it does not initiate or process a payout. The calculated charge is based on the payoutAmount provided in the request. It is recommended to retrieve the payout charge immediately before initiating a payout to ensure the returned fee reflects the current pricing. The payoutAmount should be supplied in the payout currency's major unit.
    • [Bank Transfer](https://docs.miden.co/business-accounts-1/ngn/payout/bank-transfer.md): Description This endpoint allows you to initiate an NGN bank transfer from your business account to a beneficiary bank account. The request requires the beneficiary's bank details, payout amount, transaction reference, currency, and narration. Upon successful processing, the API returns the transaction status and references for reconciliation. Usage Use this endpoint to send NGN payouts to bank accounts after validating the beneficiary details and confirming the applicable payout charge. Notes The transactionReference must be unique for each payout request to prevent duplicate processing. Ensure the beneficiary account details have been validated before initiating the payout. The business account must have sufficient available balance to cover both the payout amount and the applicable payout charge. It is recommended to call the Get Payout Charge endpoint before initiating a payout to determine the applicable fee. A successful API response indicates that the payout request has been accepted for processing. Always use the returned transactionStatus and transaction references for reconciliation and status tracking.
    • [Transfer History](https://docs.miden.co/business-accounts-1/ngn/payout/transfer-history.md): Description This endpoint retrieves the history of NGN bank transfer (payout) transactions made from your business account within a specified date range. The response includes beneficiary details, transaction references, transfer status, processing information, and pagination metadata. Usage Use this endpoint to view, reconcile, or audit outgoing bank transfer transactions. Provide the startDate and endDate query parameters in YYYY-MM-DD format to filter transactions within a specific period. Notes startDate and endDate are required and must be provided in YYYY-MM-DD format. The endpoint returns outgoing NGN bank transfers within the specified date range. processedSuccessfully should be used to confirm whether the transfer was completed successfully. Some fields such as transactionStatus , providerReference , beneficiaryKycLevel , channelCode , beneficiaryBankVerificationNumber , and nameInquiryReference may return null depending on the provider response. Results are paginated using currentPage , pageSize , totalCount , and totalPages .
• [Wallets](https://docs.miden.co/wallet-as-a-service/wallets.md): Overview The Wallet folder includes APIs related to wallet management. Wallets can represent financial holdings or accounts within the system. APIs Get Wallets Endpoint: /wallets Method: GET Description: Access a list of wallets available within the system. Parameters:
  • [Limit](https://docs.miden.co/wallet-as-a-service/wallets/limit.md): Overview The Limits folder contains APIs responsible for managing and setting various limits within the system, such as maximum transaction amounts or frequency restrictions. APIs Get Limits Endpoint: /limits Method: GET Description: Retrieve information about imposed limits, providing insights into system-wide limitations. Post Limits Endpoint: /limits Method: POST Description: Set or update limits for specific functionalities or users, allowing administrators to manage and enforce restrictions. Patch Limits Endpoint: /limits/{id} Method: PATCH Description: Adjust existing limits when needed, ensuring they remain aligned with evolving requirements.
    • [Limits Paginated](https://docs.miden.co/wallet-as-a-service/wallets/limit/limits-paginated.md): Description Retrieve information about imposed limits, such as maximum transaction amounts or frequency restrictions. Usage Use this endpoint to fetch details about limits set on transactions, including their description, amount, status, currency, expiry date, and audit information. Request URL Plain text /api/v1/wallets/limits?PageNumber=1&PageSize=20&LimitCurrency=NGN&LimitExpiryDate=2024-03-02&WalletId=0122&IsExpired=true /api/v1/wallets/limits?PageNumber=1&PageSize=20&LimitCurrency=NGN&LimitExpiryDate=2024-03-02&WalletId=0122&IsExpired=true Response Body Plain text { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "limitDetails": [ { "id": 3, "limitDescription": "Test", "limitAmount": 500, "limitStatus": "Expired", "limitCurrency": "NGN", "limitExpiryDate": "2023-09-24T00:00:00", "grantedBy": "System", "createdAt": "2023-10-04T18:47:47.3350081", "updatedBy": null, "updatedAt": "2023-10-04T19:12:46.889529", "walletId": "468f531b-4e95-4337-8861-08dbc040c6a2", "clientWallet": null, "auditLog": "Limit Updated by System on 10/04/2023 18:58:48 old expiry date 09/24/2023 00:00:00 - Limit Updated by System on 10/04/2023 19:12:46 old expiry date 09/24/2023 00:00:00 - " } ], "currentPage": 1, "pageSize": 10, "totalCount": 1, "totalPages": 1 } Response Body Explanation isSuccessful : Indicates whether the request was successful. responseCode : A code indicating the status of the response. responseMessage : A message describing the outcome of the request. limitDetails : An array containing details of the imposed limits. id : The unique identifier of the limit. limitDescription : Description of the limit. limitAmount : The maximum amount allowed for the limit. limitStatus : The current status of the limit. limitCurrency : The currency of the limit. limitExpiryDate : The expiry date of the limit. grantedBy : The entity that granted the limit. createdAt : The date and time when the limit was created. updatedBy : The entity that last updated the limit. updatedAt : The date and time when the limit was last updated. walletId : The ID of the wallet associated with the limit. clientWallet : Information about the client wallet (if applicable). auditLog : Audit log detailing the history of limit updates. Example Plain text { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "limitDetails": [ { "id": 3, "limitDescription": "Test", "limitAmount": 500, "limitStatus": "Expired", "limitCurrency": "NGN", "limitExpiryDate": "2023-09-24T00:00:00", "grantedBy": "System", "createdAt": "2023-10-04T18:47:47.3350081", "updatedBy": null, "updatedAt": "2023-10-04T19:12:46.889529", "walletId": "468f531b-4e95-4337-8861-08dbc040c6a2", "clientWallet": null, "auditLog": "Limit Updated by System on 10/04/2023 18:58:48 old expiry date 09/24/2023 00:00:00 - Limit Updated by System on 10/04/2023 19:12:46 old expiry date 09/24/2023 00:00:00 - " } ], "currentPage": 1, "pageSize": 10, "totalCount": 1, "totalPages": 1 }
    • [Limits Download](https://docs.miden.co/wallet-as-a-service/wallets/limit/limits-download.md): Description Download information about imposed limits, such as maximum transaction amounts or frequency restrictions. Usage Use this endpoint to download details about limits set on transactions, including their description, amount, status, currency, expiry date, and audit information. Request URL Plain text /api/v1/wallets/limits-download?LimitCurrency=NGN&LimitExpiryDate=2023-09-24&WalletId=468f531b-4e95-4337-8861-08dbc040c6a2&IsExpired=true /api/v1/wallets/limits-download?LimitCurrency=NGN&LimitExpiryDate=2023-09-24&WalletId=468f531b-4e95-4337-8861-08dbc040c6a2&IsExpired=true Response Body Plain text { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "limitDetails": [ { "id": 3, "limitDescription": "Test", "limitAmount": 500, "limitStatus": "Expired", "limitCurrency": "NGN", "limitExpiryDate": "2023-09-24T00:00:00", "grantedBy": "System", "createdAt": "2023-10-04T18:47:47.3350081", "updatedBy": null, "updatedAt": "2023-10-04T19:12:46.889529", "walletId": "468f531b-4e95-4337-8861-08dbc040c6a2", "clientWallet": null, "auditLog": "Limit Updated by System on 10/04/2023 18:58:48 old expiry date 09/24/2023 00:00:00 - Limit Updated by System on 10/04/2023 19:12:46 old expiry date 09/24/2023 00:00:00 - " } ] } Response Body Explanation isSuccessful : Indicates whether the request was successful. responseCode : A code indicating the status of the response. responseMessage : A message describing the outcome of the request. limitDetails : An array containing details of the imposed limits. id : The unique identifier of the limit. limitDescription : Description of the limit. limitAmount : The maximum amount allowed for the limit. limitStatus : The current status of the limit. limitCurrency : The currency of the limit. limitExpiryDate : The expiry date of the limit. grantedBy : The entity that granted the limit. createdAt : The date and time when the limit was created. updatedBy : The entity that last updated the limit. updatedAt : The date and time when the limit was last updated. walletId : The ID of the wallet associated with the limit. clientWallet : Information about the client wallet (if applicable). auditLog : Audit log detailing the history of limit updates. Example Plain text { "id": 3, "limitDescription": "Test", "limitAmount": 500, "limitStatus": "Expired", "limitCurrency": "NGN", "limitExpiryDate": "2023-09-24T00:00:00", "grantedBy": "System", "createdAt": "2023-10-04T18:47:47.3350081", "updatedBy": null, "updatedAt": "2023-10-04T19:12:46.889529", "walletId": "468f531b-4e95-4337-8861-08dbc040c6a2", "clientWallet": null, "auditLog": "Limit Updated by System on 10/04/2023 18:58:48 old expiry date 09/24/2023 00:00:00 - Limit Updated by System on 10/04/2023 19:12:46 old expiry date 09/24/2023 00:00:00 - "
    • [Create Limits](https://docs.miden.co/wallet-as-a-service/wallets/limit/create-limits.md): Description: This POST request is used to create new limit entries or update limits for a specific wallet. Usage: Send a POST request to the designated endpoint with the provided JSON body to create a new limit entry. It helps manage and enforce system-wide limits. Endpoint: Plain text /api/v1/wallets/limits /api/v1/wallets/limits Request Body: Title Description Title Description Title 201 Created: The limit was successfully created. Plain text { "id": "123456789", "limitDescription": "Test", "limitAmount": 500, "limitExpiryDate": "2024-10-24", "grantedBy": "System", "walletNumber": "90010000289", "limitCurrency": "NGN", "createdAt": "2024-03-15T12:00:00Z" } 400 Bad Request: Invalid request payload. Plain text { "error": "Invalid limitAmount value. Must be a positive number." } 401 Unauthorized: Authentication failed. Plain text { "error": "Unauthorized. Please provide a valid access token." }
    • [Create Currencies](https://docs.miden.co/wallet-as-a-service/wallets/limit/create-currencies.md): Description: This POST request is used to create new limit entries or update limits for a specific wallet. Usage: Send a POST request to the designated endpoint with the provided JSON body to create a new limit entry. It helps manage and enforce system-wide limits. Endpoint: Plain Text /api/v1/wallets/limits Request Body: Field Name Field Description Field Type Is Mandatory Example limitDescription Description of the limit String Yes “Test” limitAmount Amount of the limit Integer Yes 500 limitExpiryDate Expiry date of the limit Date Yes “2024-10-24” grantedBy Entity granting the limit String Yes “System” walletNumber Wallet number associated with the limit String Yes “90010000289” limitCurrency Currency of the limit String Yes “NGN” 201 Created: The limit was successfully created. JSON { "id": "123456789", "limitDescription": "Test", "limitAmount": 500, "limitExpiryDate": "2024-10-24", "grantedBy": "System", "walletNumber": "90010000289", "limitCurrency": "NGN", "createdAt": "2024-03-15T12:00:00Z" } 400 Bad Request: Invalid request payload. JSON { "error": "Invalid limitAmount value. Must be a positive number." } 401 Unauthorized: Authentication failed. JSON { "error": "Unauthorized. Please provide a valid access token." }
    • [Update Limits](https://docs.miden.co/wallet-as-a-service/wallets/limit/update-limits.md): Description: The PATCH endpoint for limits enables the modification of an existing parameter in the URL path. Usage: This method allows users to update specific attributes of a limit, such as its description, amount, expiry date, and the entity that granted it. operation. Endpoint: Plain text /api/v1/wallets/limits/{{limitId}} /api/v1/wallets/limits/{{limitId}} Request Body: Title Description Title Description Title 201 Created: The limit was successfully created Plain text { "id": "123456789", "limitDescription": "Update to Limit", "limitAmount": 100, "limitExpiryDate": "2024-09-24", "grantedBy": "System", "walletNumber": "90010000289", "limitCurrency": "NGN", "updatedAt": "2024-03-15T12:00:00Z" } 400 Bad Request: Invalid request payload. Plain text { "error": "Invalid limitAmount value. Must be a positive number." } 401 Unauthorized: Authentication failed. Plain text { "error": "Unauthorized. Please provide a valid access token." }
    • [Update Wallet Tier Limit](https://docs.miden.co/wallet-as-a-service/wallets/limit/update-wallet-tier-limit.md): Description: The endpoint allows users to modify the limits associated with a specific wallet tier. Usage: Modify the tier limit of a wallet, which can control the maximum values or thresholds associated with specific wallet tiers. Endpoint: Plain text /api/v1/wallets/tier-limit/{{tierId}} /api/v1/wallets/tier-limit/{{tierId}} Request Body: Title Description Title Description Title 201 Created: The limit was successfully created Plain text { "message": "Wallet tier limits updated successfully", "updatedTierLimits": { "name": "Sample", "singleCreditLimit": 1000, "singleDebitLimit": 500, "dailyCreditLimit": 5000, "dailyDebitLimit": 2000 } } 400 Bad Request: Invalid request payload. Plain text { "error": "Invalid singleCreditLimit value. Must be a positive number." } 401 Unauthorized: Authentication failed. Plain text { "error": "Unauthorized. Please provide a valid access token." }
  • [Get Wallets Paginated](https://docs.miden.co/wallet-as-a-service/wallets/get-wallets-paginated.md): #### Description Access a list of wallets available within the system. This endpoint is useful for retrieving an overview of financial holdings. #### Usage Use this endpoint to fetch a paginated list of wallets. This information can be useful for displaying wallet information in user interfaces or for performing operations on specific wallets. #### Request URL ``` /api/v1/wallets?PageNumber=1&PageSize=20 ``` #### Response Body ``` json { "clientWallets": [ { "id": "a35c8a28-2590-415e-8864-08dbc040c6a2", "walletNumber": "90010000298", "walletName": "Test Wallet Gain", "walletBalance": 0, "walletUnclearBalance": 0, "walletAvailableBalance": 0, "lienAmount": 0, "lastTransactionDate": null, "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "merchantId": "C92C56B9-8A2E-4434-78A4-08DA3B462A73", "walletOwnership": "Merchant", "thirdPartyCustomerId": null, "walletCurrency": "NGN", "thirdPartyBalance": 0, "scheme": "Customer", "closed": false, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "providerName": null, "createdAt": "2023-09-28T21:17:25.2587667", "updatedAt": "2023-09-28T21:17:25.6242388", "reservedBalance": 0, "limitAmount": 0, "freezeType": "DebitFreeze", "freezeReason": "Merchant Under investigation", "thirdPartyWalletName": null, "freezeDate": "2023-09-28T21:17:25.6242279", "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "tier": { "id": 100, "name": "Test Wallet Gain", "singleCreditLimit": 100000000, "singleDebitLimit": 100000000, "dailyCreditLimit": 5000000000, "dailyDebitLimit": 5000000000, "wallet": null, "clientWalletId": "a35c8a28-2590-415e-8864-08dbc040c6a2", "createdAt": "2023-09-28T21:17:25.2653103", "updatedAt": "2023-09-28T21:17:25.2653112" }, "lienDetails": [], "limitDetails": [] }, ... ], "currentPage": 1, "pageSize": 20, "totalPages": 1, "totalCount": 7, "isSuccessful": true, "responseMessage": "Request Successful", "responseCode": "000" } ``` #### Response Body Explanation 1. **clientWallets**: An array containing information about client wallets. - `id`: The unique identifier of the wallet. - `walletNumber`: The unique number associated with the wallet. - `walletName`: The name of the wallet. - `walletBalance`: The current balance of the wallet. - `walletUnclearBalance`: The unclear balance of the wallet. - `walletAvailableBalance`: The available balance in the wallet. - `lienAmount`: The amount of money under lien in the wallet. - `lastTransactionDate`: The date of the last transaction made on the wallet. - `status`: The status of the wallet (e.g., Active). - `clientDetailsId`: The unique identifier of the client details associated with the wallet. - `merchantId`: The unique identifier of the merchant associated with the wallet. - `walletOwnership`: Indicates whether the wallet is owned by a merchant or a customer. - `thirdPartyCustomerId`: The unique identifier of the third-party customer associated with the wallet. - `walletCurrency`: The currency of the wallet. - `thirdPartyBalance`: The balance of the third party associated with the wallet. - `scheme`: The scheme of the wallet (e.g., Customer). - `closed`: Indicates whether the wallet is closed. - `thirdPartyWalletNumber`: The unique number associated with the third-party wallet. - `thirdPartyBankName`: The name of the bank associated with the third party. - `providerName`: The name of the provider associated with the wallet. - `createdAt`: The date and time when the wallet record was created. - `updatedAt`: The date and time when the wallet record was last updated. - `reservedBalance`: The reserved balance in the wallet. - `limitAmount`: The limit amount set for the wallet. - `freezeType`: The type of freeze applied to the wallet. - `freezeReason`: The reason for the freeze applied to the wallet. - `thirdPartyWalletName`: The name of the third-party wallet. - `freezeDate`: The date and time when the freeze was applied to the wallet. - `virtualAccountProviderCode`: The code of the virtual account provider associated with the wallet. - `walletMinimumBalance`: The minimum balance required for the wallet. - `tier`: Information about the tier associated with the wallet. - `lienDetails`: Details of any liens associated with the wallet. - `limitDetails`: Details of any limits set for the wallet. 1. **currentPage**: The current page number of the results. 2. **pageSize**: The maximum number of items per page. 3. **totalPages**: The total number of pages based on the page size and total count. 4. **totalCount**: The total number of client wallets matching the query criteria. 5. **isSuccessful**: Indicates whether the request was successful. 6. **responseMessage**: A message describing the outcome of the request. 7. **responseCode**: A code indicating the status of the response (e.g., success, error). #### Example ``` json { "clientWallets": [ { "id": "a35c8a28-2590-415e-8864-08dbc040c6a2", "walletNumber": "90010000298", "walletName": "Test Wallet Gain", "walletBalance": 0, "walletUnclearBalance": 0, "walletAvailableBalance": 0, "lienAmount": 0, "lastTransactionDate": null, "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "merchantId": "C92C56B9-8A2E-4434-78A4-08DA3B462A73", "walletOwnership": "Merchant", "thirdPartyCustomerId": null, "walletCurrency": "NGN", "thirdPartyBalance": 0, "scheme": "Customer", "closed": false, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "providerName": null, "createdAt": "2023-09-28T21:17:25.2587667", "updatedAt": "2023-09-28T21:17:25.6242388", "reservedBalance": 0, "limitAmount": 0, "freezeType": "DebitFreeze", "freezeReason": "Merchant Under investigation", "thirdPartyWalletName": null, "freezeDate": "2023-09-28T21:17:25.6242279", "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "tier": { "id": 100, "name": "Test Wallet Gain", "singleCreditLimit": 100000000, "singleDebitLimit": 100000000, "dailyCreditLimit": 5000000000, "dailyDebitLimit": 5000000000, "wallet": null, "clientWalletId": "a35c8a28-2590-415e-8864-08dbc040c6a2", "createdAt": "2023-09-28T21:17:25.2653103", "updatedAt": "2023-09-28T21:17:25.2653112" }, "lienDetails": [], "limitDetails": [] }, ... ], "currentPage": 1, "pageSize": 20, "totalPages": 1, "totalCount": 7, "isSuccessful": true, "responseMessage": "Request Successful", "responseCode": "000" } ```
  • [Get Wallets](https://docs.miden.co/wallet-as-a-service/wallets/get-wallets.md): #### Description: Access a list of wallets available within the system. This endpoint is useful for retrieving an overview of financial holdings. #### Usage: Access a list of wallets available within the system. This endpoint is useful for retrieving an overview of financial holdings. This endpoint is used to fetch details of client wallets, including their balances, status, ownership, and associated limits. #### Request URL ``` /api/v1/wallets/download?MerchantId=B76BA034-64C9-4739-E0C3-08DBD940B8D1 ``` #### Response Body ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "clientWallets": [ { "id": "a35c8a28-2590-415e-8864-08dbc040c6a2", "walletNumber": "90010000298", "walletName": "Test Wallet Gain", "walletBalance": 0, "walletUnclearBalance": 0, "walletAvailableBalance": 0, "lienAmount": 0, "lastTransactionDate": null, "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "merchantId": "C92C56B9-8A2E-4434-78A4-08DA3B462A73", "walletOwnership": "Merchant", "thirdPartyCustomerId": null, "walletCurrency": "NGN", "thirdPartyBalance": 0, "scheme": "Customer", "closed": false, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "providerName": null, "createdAt": "2023-09-28T21:17:25.2587667", "updatedAt": "2023-09-28T21:17:25.6242388", "reservedBalance": 0, "limitAmount": 0, "freezeType": "DebitFreeze", "freezeReason": "Merchant Under investigation", "thirdPartyWalletName": null, "freezeDate": "2023-09-28T21:17:25.6242279", "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "tier": { "id": 100, "name": "Test Wallet Gain", "singleCreditLimit": 100000000, "singleDebitLimit": 100000000, "dailyCreditLimit": 5000000000, "dailyDebitLimit": 5000000000, "wallet": null, "clientWalletId": "a35c8a28-2590-415e-8864-08dbc040c6a2", "createdAt": "2023-09-28T21:17:25.2653103", "updatedAt": "2023-09-28T21:17:25.2653112" }, "lienDetails": [], "limitDetails": [] } ] } ``` #### Response Body Explanation - `isSuccessful`: Indicates whether the request was successful. - `responseCode`: A code indicating the status of the response (e.g., success, error). - `responseMessage`: A message describing the outcome of the request. - `clientWallets`: An array containing information about client wallets. - `id`: The unique identifier of the wallet. - `walletNumber`: The unique identifier of the wallet number. - `walletName`: The name of the wallet. - `walletBalance`: The current balance of the wallet. - `walletUnclearBalance`: The unclear balance of the wallet. - `walletAvailableBalance`: The available balance of the wallet. - `lienAmount`: The amount of money under lien in the wallet. - `lastTransactionDate`: The date of the last transaction made on the wallet. - `status`: The status of the wallet (e.g., active, closed). - `clientDetailsId`: The unique identifier of the client details associated with the wallet. - `merchantId`: The unique identifier of the merchant associated with the wallet. - `walletOwnership`: The ownership status of the wallet (e.g., merchant, customer). - `thirdPartyCustomerId`: The unique identifier of the third-party customer associated with the wallet. - `walletCurrency`: The currency of the wallet. - `thirdPartyBalance`: The balance of the third-party associated with the wallet. - `scheme`: The scheme of the wallet (e.g., customer, merchant). - `closed`: Indicates whether the wallet is closed. - `thirdPartyWalletNumber`: The wallet number of the third-party associated with the wallet. - `thirdPartyBankName`: The bank name of the third-party associated with the wallet.z - `providerName`: The provider name associated with the wallet. - `createdAt`: The date and time when the wallet was created. - `updatedAt`: The date and time when the wallet was last updated. - `reservedBalance`: The reserved balance of the wallet. - `limitAmount`: The limit amount of the wallet. - `freezeType`: The type of freeze applied to the wallet (e.g., debit freeze, credit freeze). - `freezeReason`: The reason for the freeze applied to the wallet. - `thirdPartyWalletName`: The name of the third-party wallet associated with the wallet. - `freezeDate`: The date and time when the freeze was applied to the wallet. - `virtualAccountProviderCode`: The provider code of the virtual account associated with the wallet. - `walletMinimumBalance`: The minimum balance required for the wallet. - `tier`: Details about the tier associated with the wallet. - `id`: The unique identifier of the tier. - `name`: The name of the tier. - `singleCreditLimit`: The single credit limit of the tier. - `singleDebitLimit`: The single debit limit of the tier. - `dailyCreditLimit`: The daily credit limit of the tier. - `dailyDebitLimit`: The daily debit limit of the tier. - `createdAt`: The date and time when the tier was created. - `updatedAt`: The date and time when the tier was last updated. - `lienDetails`: Details about any liens associated with the wallet. - `limitDetails`: Details about any limits associated with the wallet. #### Example ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "clientWallets": [ { "id": "a35c8a28-2590-415e-8864-08dbc040c6a2", "walletNumber": "90010000298", "walletName": "Test Wallet Gain", "walletBalance": 0, "walletUnclearBalance": 0, "walletAvailableBalance": 0, "lienAmount": 0, "lastTransactionDate": null, "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "merchantId": "C92C56B9-8A2E-4434-78A4-08DA3B462A73", "walletOwnership": "Merchant", "thirdPartyCustomerId": null, "walletCurrency": "NGN", "thirdPartyBalance": 0, "scheme": "Customer", "closed": false, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "providerName": null, "createdAt": "2023-09-28T21:17:25.2587667", "updatedAt": "2023-09-28T21:17:25.6242388", "reservedBalance": 0, "limitAmount": 0, "freezeType": "DebitFreeze", "freezeReason": "Merchant Under investigation", "thirdPartyWalletName": null, "freezeDate": "2023-09-28T21:17:25.6242279", "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "tier": { "id": 100, "name": "Test Wallet Gain", "singleCreditLimit": 100000000, "singleDebitLimit": 100000000, "dailyCreditLimit": 5000000000, "dailyDebitLimit": 5000000000, "wallet": null, "clientWalletId": "a35c8a28-2590-415e-8864-08dbc040c6a2", "createdAt": "2023-09-28T21:17:25.2653103", "updatedAt": "2023-09-28T21:17:25.2653112" }, "lienDetails": [], "limitDetails": [] } ] } ```
  • [Get Schemes](https://docs.miden.co/wallet-as-a-service/wallets/get-schemes.md): #### Description This endpoint allows you to retrieve a list of schemes, which represent different categories or types within the system. #### Usage The "GET SCHEMES" endpoint can be used to retrieve a list of available scheme types associated with wallets, facilitating categorization and management within the system. #### Request URL ``` /api/v1/wallets/schemes ``` #### Response Body ``` json [ { "id": 1, "schemeName": "Liability", "schemeCode": "Liability" }, { "id": 2, "schemeName": "Income", "schemeCode": "Income" }, { "id": 3, "schemeName": "Payable", "schemeCode": "Payable" }, { "id": 4, "schemeName": "Receivable", "schemeCode": "Receivable" }, { "id": 5, "schemeName": "Expense", "schemeCode": "Expense" }, { "id": 6, "schemeName": "Customer", "schemeCode": "Customer" }, { "id": 7, "schemeName": "Collection", "schemeCode": "Collection" } ] ``` #### Response Body Explanation - `id`: The unique identifier for the scheme. - `schemeName`: The name of the scheme. - `schemeCode`: The code associated with the scheme. #### Schemes Explained: - **Liability** - **Description**: Represents debts or obligations that the wallet holder is responsible for. Liabilities typically include loans, mortgages, and other financial commitments that must be paid back over time. - **Usage**: Used to track and manage financial obligations, ensuring accurate accounting of what is owed by the wallet holder. - **Income** - **Description**: Refers to the earnings or revenue generated by the wallet holder. This can include salaries, business revenue, interest from investments, and other sources of monetary inflow. - **Usage**: Used in tracking all incoming funds, facilitating budgeting and financial planning by providing a clear view of earnings. - **Payable** - **Description**: Denotes amounts that the wallet holder is obligated to pay to suppliers or creditors. These are usually short-term debts that need to be settled within a specific period. - **Usage**: Used for managing short-term liabilities, ensuring timely payments to suppliers or creditors, and maintaining good financial relationships. - **Receivable** - **Description**: Represents amounts that are owed to the wallet holder by customers or debtors. These are expected to be collected within a certain timeframe. - **Usage**: Used in tracking of outstanding amounts to be received, aiding in cash flow management and ensuring timely collection of dues. - **Expense** - **Description**: Covers all costs incurred by the wallet holder in the course of their activities. Expenses can include operational costs, purchases, utilities, and other outflows of money. - **Usage**: Helps in monitoring and controlling spending, providing insights into where money is being spent and identifying areas for cost reduction. - **Customer** - **Description**: Refers to individuals or entities that purchase goods or services from the wallet holder. This scheme focuses on managing customer-related financial transactions. - **Usage**: Used to track customer payments and balances, facilitating effective customer relationship management and ensuring accurate accounting of customer transactions. - **Collection** - **Description**: Involves the gathering of funds, either from receivables or other sources. It focuses on the process of collecting money owed to the wallet holder. - **Usage**: Essential for managing the collection process, ensuring that all owed amounts are gathered efficiently, and maintaining positive cash flow.
  • [Get Internal Wallets](https://docs.miden.co/wallet-as-a-service/wallets/get-internal-wallets.md): **Description:** The "GET INTERNAL WALLETS" endpoint retrieves a list of internal wallets within the system, providing details such as wallet number, name, currency, and balance. **Usage:** This endpoint is used to fetch information about internal wallets, aiding in internal financial management and tracking. **Request URL:** ``` /api/v1/wallets/internal ``` **Response Body:** ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "wallets": [ { "id": "93132227-b5b3-46db-33b6-08dbc1e51d93", "walletNumber": "90010000307", "walletName": "Passpoint Receivable (AUD)", "walletCurrency": "AUD", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "5bef8382-56c2-442a-88be-ec6a2e28e79a", "checkSumValue": "5B8A2E72A0E7A3F7CD854E44CC151332", "checkSumValue2": "5B8A2E72A0E7A3F7CD854E44CC151332", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Receivable", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-30T18:43:19.0497687", "updatedAt": "2023-09-30T18:43:19.0836258", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "2c3bb383-634f-4809-2bfe-08dbbf668180", "walletNumber": "90010000013", "walletName": "Passpoint Liability (GSH) 1", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "ee34877c-c935-4f78-94c9-c708e8ac8912", "checkSumValue": "C72B24356E85918323D30686416AE87B", "checkSumValue2": "C72B24356E85918323D30686416AE87B", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:06.3721314", "updatedAt": "2023-09-27T15:32:06.372177", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "1f4d7ea3-3441-4321-2c01-08dbbf668180", "walletNumber": "90010000022", "walletName": "Passpoint Liability (GSH) 2", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "b7b08897-7d90-443b-b1c9-7822d2e04252", "checkSumValue": "98FA010A7B371EA632C74F2EF5A6E230", "checkSumValue2": "98FA010A7B371EA632C74F2EF5A6E230", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:07.6564161", "updatedAt": "2023-09-27T15:32:07.6564583", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "4658d199-4cc4-4e1a-2c04-08dbbf668180", "walletNumber": "90010000031", "walletName": "Passpoint Liability (GSH) 3", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "35b6d4c3-65f6-47bb-9f8d-0655b556f859", "checkSumValue": "EA2BCDEB77F2B47EDB7B1DB34C3F49B6", "checkSumValue2": "EA2BCDEB77F2B47EDB7B1DB34C3F49B6", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:08.9042383", "updatedAt": "2023-09-27T15:32:08.9043113", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "138e90ca-b1fa-44cb-2c07-08dbbf668180", "walletNumber": "90010000040", "walletName": "Passpoint Liability (GSH) 4", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "960ff8ec-51ee-4caa-aefa-8a5734ec48b2", "checkSumValue": "3D330B6F79FEB03E417EB1E1CC9E0B87", "checkSumValue2": "3D330B6F79FEB03E417EB1E1CC9E0B87", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:10.0793966", "updatedAt": "2023-09-27T15:32:10.079441", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "e08430ba-7828-4735-2c0a-08dbbf668180", "walletNumber": "90010000049", "walletName": "Passpoint Liability (GSH) 5", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "93e64f3a-012b-476d-aa12-ccbec4aa7194", "checkSumValue": "344E26310D2D976D33297D6AAAFEAB64", "checkSumValue2": "344E26310D2D976D33297D6AAAFEAB64", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:11.2691687", "updatedAt": "2023-09-27T15:32:11.2692266", "limitDetails": [], "lienDetails": [], "tier": null }, { "id": "324cffaa-d099-41d6-2c0d-08dbbf668180", "walletNumber": "90010000058", "walletName": "Passpoint Income (GSH) 1", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "1aa44464-4d28-47de-917b-b65344652e00", "checkSumValue": "B8D452A3DB4F652E764378A3AAF9EC35", "checkSumValue2": "B8D452A3DB4F652E764378A3AAF9EC35", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Income", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:12.4167673", "updatedAt": "2023-09-27T15:32:12.4168284", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "9989ade3-f092-4c58-2c10-08dbbf668180", "walletNumber": "90010000067", "walletName": "Passpoint Income (GSH) 2", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "11085e59-93b7-48bb-beef-9e2476a98566", "checkSumValue": "B6757BBAA082C7AC935E2874541F9CB1", "checkSumValue2": "B6757BBAA082C7AC935E2874541F9CB1", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Income", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:13.591775", "updatedAt": "2023-09-27T15:32:13.5918247", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "6c231d8c-b9c4-4be0-2c13-08dbbf668180", "walletNumber": "90010000076", "walletName": "Passpoint Income (GSH) 3", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "2c2391cf-63f9-434d-8514-43c7ad446f41", "checkSumValue": "78362ABEEE26894B7D2B57875626B669", "checkSumValue2": "78362ABEEE26894B7D2B57875626B669", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Income", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:14.7775471", "updatedAt": "2023-09-27T15:32:14.7775914", "limitDetails": [], "lienDetails": [], "tier": null } } ] } ``` **Explanation:** - `isSuccessful`: Indicates whether the request was successful. - `responseCode`: Code indicating the status of the response. - `responseMessage`: Message associated with the response code. - `wallets`: An array containing details of internal wallets. - `id`: Unique identifier for the wallet. - `walletNumber`: Unique number assigned to the wallet. - `walletName`: Name assigned to the wallet. - `walletCurrency`: Currency associated with the wallet. - `walletBalance`: Current balance of the wallet. - `walletAvailableBalance`: Available balance in the wallet. - `walletUnclearBalance`: Balance pending clearance or verification. - `reservedBalance`: Amount of funds reserved for specific purposes. - `lienAmount`: Amount of funds placed under a lien or hold. - `limitAmount`: Maximum limit allowed for transactions in the wallet. - `lastTransactionDate`: Timestamp of the last transaction made with the wallet. - `walletHash`: Unique hash value associated with the wallet. - `checkSumValue`, `checkSumValue2`: Checksum values for data integrity. - `status`: Current status of the wallet (e.g., "A" for active). - `clientDetailsId`: Unique identifier for the client associated with the wallet. - `closed`: Indicates whether the wallet is closed or not. - `closedAt`: Timestamp indicating when the wallet was closed, if applicable. - `merchantId`: Unique identifier for the merchant associated with the wallet, if any. - `scheme`: Financial scheme or category to which the wallet belongs. - `walletOwnership`: Indicates whether the wallet is internal or external. - `thirdPartyCustomerId`: Unique identifier for the third-party customer associated with the wallet, if any. - `thirdPartyBalance`: Balance associated with a third-party customer, if applicable. - `thirdPartyWalletNumber`, `thirdPartyBankName`, `thirdPartyWalletName`: Details related to third-party association. - `freezeType`, `freezeReason`, `freezeDate`: Details of any freeze placed on the wallet. - `providerName`, `virtualAccountProviderCode`: Provider-related details. - `walletMinimumBalance`: Minimum balance required for the wallet. - `createdAt`, `updatedAt`: Timestamps indicating creation and last update of the wallet. - `limitDetails`, `lienDetails`: Additional details about transaction limits and liens, if any. - `tier`: Information about the tier associated with the wallet, if applicable. **Example:** ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "wallets": [ { "id": "93132227-b5b3-46db-33b6-08dbc1e51d93", "walletNumber": "90010000307", "walletName": "Passpoint Receivable (AUD)", "walletCurrency": "AUD", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "5bef8382-56c2-442a-88be-ec6a2e28e79a", "checkSumValue": "5B8A2E72A0E7A3F7CD854E44CC151332", "checkSumValue2": "5B8A2E72A0E7A3F7CD854E44CC151332", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Receivable", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-30T18:43:19.0497687", "updatedAt": "2023-09-30T18:43:19.0836258", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "2c3bb383-634f-4809-2bfe-08dbbf668180", "walletNumber": "90010000013", "walletName": "Passpoint Liability (GSH) 1", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "ee34877c-c935-4f78-94c9-c708e8ac8912", "checkSumValue": "C72B24356E85918323D30686416AE87B", "checkSumValue2": "C72B24356E85918323D30686416AE87B", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:06.3721314", "updatedAt": "2023-09-27T15:32:06.372177", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "1f4d7ea3-3441-4321-2c01-08dbbf668180", "walletNumber": "90010000022", "walletName": "Passpoint Liability (GSH) 2", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "b7b08897-7d90-443b-b1c9-7822d2e04252", "checkSumValue": "98FA010A7B371EA632C74F2EF5A6E230", "checkSumValue2": "98FA010A7B371EA632C74F2EF5A6E230", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:07.6564161", "updatedAt": "2023-09-27T15:32:07.6564583", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "4658d199-4cc4-4e1a-2c04-08dbbf668180", "walletNumber": "90010000031", "walletName": "Passpoint Liability (GSH) 3", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "35b6d4c3-65f6-47bb-9f8d-0655b556f859", "checkSumValue": "EA2BCDEB77F2B47EDB7B1DB34C3F49B6", "checkSumValue2": "EA2BCDEB77F2B47EDB7B1DB34C3F49B6", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:08.9042383", "updatedAt": "2023-09-27T15:32:08.9043113", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "138e90ca-b1fa-44cb-2c07-08dbbf668180", "walletNumber": "90010000040", "walletName": "Passpoint Liability (GSH) 4", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "960ff8ec-51ee-4caa-aefa-8a5734ec48b2", "checkSumValue": "3D330B6F79FEB03E417EB1E1CC9E0B87", "checkSumValue2": "3D330B6F79FEB03E417EB1E1CC9E0B87", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:10.0793966", "updatedAt": "2023-09-27T15:32:10.079441", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "e08430ba-7828-4735-2c0a-08dbbf668180", "walletNumber": "90010000049", "walletName": "Passpoint Liability (GSH) 5", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "93e64f3a-012b-476d-aa12-ccbec4aa7194", "checkSumValue": "344E26310D2D976D33297D6AAAFEAB64", "checkSumValue2": "344E26310D2D976D33297D6AAAFEAB64", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Liability", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:11.2691687", "updatedAt": "2023-09-27T15:32:11.2692266", "limitDetails": [], "lienDetails": [], "tier": null }, { "id": "324cffaa-d099-41d6-2c0d-08dbbf668180", "walletNumber": "90010000058", "walletName": "Passpoint Income (GSH) 1", "walletCurrency": "GSH", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "1aa44464-4d28-47de-917b-b65344652e00", "checkSumValue": "B8D452A3DB4F652E764378A3AAF9EC35", "checkSumValue2": "B8D452A3DB4F652E764378A3AAF9EC35", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": null, "scheme": "Income", "walletOwnership": "Internal", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "freezeType": null, "freezeReason": null, "freezeDate": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 0, "createdAt": "2023-09-27T15:32:12.4167673", "updatedAt": "2023-09-27T15:32:12.4168284", "limitDetails": [], "lienDetails": [], "tier": null } { "id": "9989ade3-f092-4c58-2c10-08dbbf668180", "walletNumber": "90010000067", "walletName": "Passpoint Income (GSH) 2", "walletCurrency": "GSH", "walletBalance": 5000.00, "walletAvailableBalance": 4500.00, "walletUnclearBalance": 0, "reservedBalance": 500.00, "lienAmount": 0, "limitAmount": 10000.00, "lastTransactionDate": "2023-09-28T08:30:00", "walletHash": "11085e59-93b7-48bb-beef-9e2476a98566", "checkSumValue": "B6757BBAA082C7AC935E2874541F9CB1", "checkSumValue2": "B6757BBAA082C7AC935E2874541F9CB1", "status": "A", "clientDetailsId": "12345678-1234-5678-1234-567812345678", "closed": false, "closedAt": null, "merchantId": "12345678-1234-5678-1234-567812345678", "scheme": "Income", "walletOwnership": "Internal", "thirdPartyCustomerId": "98765432-9876-5432-9876-543298765432", "thirdPartyBalance": 0, "thirdPartyWalletNumber": "98765432", "thirdPartyBankName": "Example Bank", "thirdPartyWalletName": "Example Wallet", "freezeType": "Temporary", "freezeReason": "Fraudulent Activity", "freezeDate": "2023-09-28T08:30:00", "providerName": "Passpoint", "virtualAccountProviderCode": "1234", "walletMinimumBalance": 100.00, "createdAt": "2023-09-27T15:32:13.591775", "updatedAt": "2023-09-27T15:32:13.5918247", "limitDetails": [ { "id": "12345678-1234-5678-1234-567812345678", "limitType": "Daily", "limitAmount": 5000.00 } ], "lienDetails": [ { "id": "12345678-1234-5678-1234-567812345678", "lienReason": "Payment Pending", "lienAmount": 500.00 } ], "tier": "Gold" } { "id": "6c231d8c-b9c4-4be0-2c13-08dbbf668180", "walletNumber": "90010000076", "walletName": "Passpoint Income (GSH) 3", "walletCurrency": "GSH", "walletBalance": 2000.00, "walletAvailableBalance": 1800.00, "walletUnclearBalance": 0, "reservedBalance": 200.00, "lienAmount": 0, "limitAmount": 5000.00, "lastTransactionDate": "2023-09-28T09:45:00", "walletHash": "2c2391cf-63f9-434d-8514-43c7ad446f41", "checkSumValue": "78362ABEEE26894B7D2B57875626B669", "checkSumValue2": "78362ABEEE26894B7D2B57875626B669", "status": "A", "clientDetailsId": "98765432-9876-5432-9876-543298765432", "closed": false, "closedAt": null, "merchantId": "98765432-9876-5432-9876-543298765432", "scheme": "Income", "walletOwnership": "Internal", "thirdPartyCustomerId": "12345678-1234-5678-1234-567812345678", "thirdPartyBalance": 0, "thirdPartyWalletNumber": "12345678", "thirdPartyBankName": "Example Bank", "thirdPartyWalletName": "Example Wallet", "freezeType": "Permanent", "freezeReason": "Account Closure", "freezeDate": "2023-09-28T09:45:00", "providerName": "Passpoint", "virtualAccountProviderCode": "5678", "walletMinimumBalance": 200.00, "createdAt": "2023-09-27T15:32:14.7775471", "updatedAt": "2023-09-27T15:32:14.7775914", "limitDetails": [ { "id": "98765432-9876-5432-9876-543298765432", "limitType": "Monthly", "limitAmount": 2000.00 } ], "lienDetails": [], "tier": "Silver" } { ] } ```
  • [Create Internal Wallet](https://docs.miden.co/wallet-as-a-service/wallets/create-internal-wallet.md): This ednpoint creates an internal wallet, typically used for system-specific transactions or accounting purposes.
  • [Get Wallet By Id](https://docs.miden.co/wallet-as-a-service/wallets/get-wallet-by-id.md): Description: This endpoint fetches detailed information about a specific wallet, identified by its unique identifier. Usage: Use this endpoint to fetch and examine detailed information about a specific wallet identified by its ID. Request URL Plain text /api/v1/wallets/{{passpointWalletId}} /api/v1/wallets/{{passpointWalletId}} Response Body Plain text { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "data": { "id": "077d5336-6d68-4b75-fd16-08dbbd272ca6", "walletNumber": "90010000310", "walletName": "Test Wallet Gain", "walletCurrency": "NGN", "walletBalance": 0, "walletAvailableBalance": 0, "walletUnclearBalance": 0, "reservedBalance": 0, "lienAmount": 0, "limitAmount": 0, "lastTransactionDate": null, "walletHash": "f998e236-ff40-4e0c-af8d-5feb56016de5", "checkSumValue": "63D9CC8AB44B0D74997A3B43ADD7CBD4", "checkSumValue2": "63D9CC8AB44B0D74997A3B43ADD7CBD4", "status": "A", "clientDetailsId": "00000000-0000-0000-0000-000000000000", "closed": false, "closedAt": null, "merchantId": "c92c56b9-8a2e-4434-78a4-08da3b462a73", "scheme": "Customer", "walletOwnership": "Merchant", "thirdPartyCustomerId": null, "thirdPartyBalance": 0, "thirdPartyWalletNumber": null, "thirdPartyBankName": null, "thirdPartyWalletName": null, "thirdPartyInstanceId": null, "providerName": null, "virtualAccountProviderCode": null, "walletMinimumBalance": 2000, "createdAt": "2023-09-24T18:53:35.2985162", "updatedAt": "2023-09-24T18:53:35.3063918", "limitDetails": [], "lienDetails": [], "tier": null } } Response Body Explanation: isSuccessful: Indicates if the request was successful. responseCode: A code representing the result of the request. responseMessage: A message accompanying the response code. data : Object containing details of the wallet. id : Unique identifier of the wallet. walletNumber : Unique wallet number. walletName : Name of the wallet. walletCurrency : Currency of the wallet. walletBalance : Current balance of the wallet. walletAvailableBalance : Available balance for transactions. walletUnclearBalance : Balance that is not yet confirmed. reservedBalance : Amount reserved for pending transactions. lienAmount : Amount held as a lien. limitAmount : Transaction limit for the wallet. lastTransactionDate : Date of the last transaction. walletHash : Hash value of the wallet. checkSumValue : Checksum value for validation. status : Current status of the wallet. clientDetailsId : Identifier for client details. closed : Indicates if the wallet is closed. closedAt : Date and time when the wallet was closed. merchantId : Identifier of the merchant. scheme : Type of scheme associated with the wallet. walletOwnership : Ownership status of the wallet. thirdPartyCustomerId : Identifier for third-party customer. thirdPartyBalance : Balance of third-party customer. thirdPartyWalletNumber : Number of third-party wallet. thirdPartyBankName : Name of the third-party bank. thirdPartyWalletName : Name of the third-party wallet. thirdPartyInstanceId : Identifier for third-party instance. providerName : Name of the provider. virtualAccountProviderCode : Code for virtual account provider. walletMinimumBalance : Minimum balance required for the wallet. createdAt : Date and time when the wallet was created. updatedAt : Date and time when the wallet was last updated. limitDetails : Details of transaction limits associated with the wallet. lienDetails : Details of liens placed on the wallet. tier : Tier classification of the wallet. Example**:** Plain text { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "data": { "id": "077d5336-6d68-4b75-fd16-08dbbd272ca6", "walletNumber": "90010000310", "walletName": "Test Wallet Gain", "walletCurrency": "NGN", "walletBalance": 5000.00, "walletAvailableBalance": 4500.00, "walletUnclearBalance": 0, "reservedBalance": 500.00, "lienAmount": 0, "limitAmount": 10000.00, "lastTransactionDate": "2023-09-28T08:30:00", "walletHash": "f998e236-ff40-4e0c-af8d-5feb56016de5", "checkSumValue": "63D9CC8AB44B0D74997A3B43ADD7CBD4", "checkSumValue2": "63D9CC8AB44B0D74997A3B43ADD7CBD4", "status": "A", "clientDetailsId": "12345678-1234-5678-1234-567812345678", "closed": false, "closedAt": null, "merchantId": "c92c56b9-8a2e-4434-78a4-08da3b462a73", "scheme": "Customer", "walletOwnership": "Merchant", "thirdPartyCustomerId": "98765432-9876-5432-9876-543298765432", "thirdPartyBalance": 0, "thirdPartyWalletNumber": "98765432", "thirdPartyBankName": "Example Bank", "thirdPartyWalletName": "Example Wallet", "thirdPartyInstanceId": "12345678-1234-5678-1234-567812345678", "providerName": "Passpoint", "virtualAccountProviderCode": "1234", "walletMinimumBalance": 2000.00, "createdAt": "2023-09-24T18:53:35.2985162", "updatedAt": "2023-09-24T18:53:35.3063918", "limitDetails": [ { "id": "12345678-1234-5678-1234-567812345678", "limitType": "Daily", "limitAmount": 5000.00 } ], "lienDetails": [], "tier": "Gold" } }
  • [Create Wallet](https://docs.miden.co/wallet-as-a-service/wallets/create-wallet.md): Create a new wallet, potentially representing a financial account or entity. This API allows for the expansion of financial resources.
  • [Update Wallet](https://docs.miden.co/wallet-as-a-service/wallets/update-wallet.md): Update an existing wallet, adjusting its attributes or properties. This endpoint facilitates wallet maintenance and adjustments.
  • [Link Virtual Account](https://docs.miden.co/wallet-as-a-service/wallets/link-virtual-account.md): Update an existing wallet, adjusting its attributes or properties. This endpoint facilitates wallet maintenance and adjustments.
  • [Unfreeze Wallet](https://docs.miden.co/wallet-as-a-service/wallets/unfreeze-wallet.md): Update an existing wallet, adjusting its attributes or properties. This endpoint facilitates wallet maintenance and adjustments.
• [Transactions](https://docs.miden.co/wallet-as-a-service/transactions.md): Overview The Transactions folder contains APIs that facilitate various financial transactions and operations. These APIs cover a wide range of actions, including transaction retrieval, creation, reversal, fund transfers, and currency conversion. APIs Get all posted transactions Endpoint: /transactions Method: GET Description: Retrieve a comprehensive list of all previously posted transactions within the system. Parameters: Title Description Title Post Create Transaction Endpoint: /transactions Method: POST Description: Initiate the creation of new financial transactions, supporting various operations. Parameters: Title Description Title Post Reverse Transaction Endpoint: /transactions/{id}/reverse Method: POST Description: Trigger a reversal process for a previous transaction, correcting errors or unintended transactions. Parameters: Title Description Title Post Fund Transfer Endpoint: /fund-transfer Method: POST Description: Enable the transfer of funds between accounts or entities, supporting various financial transactions. Parameters: Title Description Title Post Fund Wallet Endpoint: /fund-wallet Method: POST Description: Fund a specific wallet, increasing its balance to accommodate financial operations. Parameters: Title Description Title Post Funds Transfer Cross Currency Endpoint: /cross-currency-transfer Method: POST Description: Execute funds transfer between wallets with differing currencies, often involving currency conversion. Parameters: Title Description Title Post Currency Conversion Endpoint: /currency-conversion Method: POST Description: Perform currency conversion operations, enabling transactions in different currencies. Parameters: Title Description Title
  • [Lien](https://docs.miden.co/wallet-as-a-service/transactions/lien.md): Overview The Lien folder contains APIs related to lien management. These APIs allow for lien retrieval, creation, updates, and unblocking. APIs Get All Liens Endpoint: /liens Method: GET Description: Retrieve a comprehensive list of all active liens or encumbrances within the system. Parameters: Parameter Type Description Authorization Bearer Authentication token obtained at login. Post Add Lien Endpoint: /liens Method: POST Description: Add a new lien or encumbrance to an account or asset, indicating a legal or financial interest. Parameters: Parameter Type Description Authorization Bearer Authentication token obtained at login. (Other parameters for adding a lien) Post Advice Endpoint: /liens/{id}/advice Method: POST Description: Provide advisory notes or comments related to specific liens, potentially influencing further actions or decisions. Parameters: Parameter Type Description Authorization Bearer Authentication token obtained at login. id string Unique identifier of the lien to advise on. (Other parameters for providing advice) Post Update Endpoint: /liens/{id} Method: POST Description: Update existing lien details, ensuring accuracy and alignment with evolving circumstances. Parameters: Parameter Type Description Authorization Bearer Authentication token obtained at login. id string Unique identifier of the lien to update. (Other parameters for updating the lien) Post Unblock & Debit Instant Endpoint: /liens/{id}/unblock-debit-instant Method: POST Description: Initiate an immediate unblocking and debit process related to a lien, often involving real-time financial adjustments. Parameters: Parameters: Parameter Type Description Authorization Bearer Authentication token obtained at login. id string Unique identifier of the lien to unblock and debit. (Other parameters for instant unblocking and debit) Post Unblock & Debit Async Endpoint: /liens/{id}/unblock-debit-async Method: POST Description: Trigger an asynchronous unblocking and debit process associated with a lien, allowing for more complex or time-delayed operations. Parameters: Parameter Type Description Authorization Bearer Authentication token obtained at login. id string Unique identifier of the lien for asynchronous unblocking and debit. (Other parameters for asynchronous unblocking and debit)
    • [All Liens](https://docs.miden.co/wallet-as-a-service/transactions/lien/all-liens.md): ### Description: Retrieves all active liens associated with wallets. ### Usage: Use this endpoint to fetch information about all active liens for wallets within the system. ### Request URL: ``` /api/v1/liens ``` ### Response Body: ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "liens": [ { "id": 1, "walletNumber": "90010000298", "lienAmount": 50000, "lienStartDate": "2023-10-03T00:00:00", "lienReference": "045dc99be7d046ddb8a6efd829955b75169636455210030822485459c01de44b65b8b174f12dd74aa5", "lienCurrency": "NGN", "validUntil": "2023-10-04T00:00:00", "eventLienAmount": 0, "lienRemarks": "Test Lien", "isActive": true, "transactionType": null, "requestedBy": "chinedu@passpoint.com", "createdAt": "2023-10-03T20:22:32.8780785", "updatedAt": "2023-10-03T20:22:32.8780786", "walletId": "a35c8a28-2590-415e-8864-08dbc040c6a2", "clientWallet": null } ], "currentPage": 1, "pageSize": 10, "totalCount": 1, "totalPages": 1 } ``` ### Response Body Explanation: - `isSuccessful`: Indicates whether the request was successful or not. - `responseCode`: A code indicating the status of the response. - `responseMessage`: A message providing additional information about the response. - `liens`: An array containing information about all the liens. - `id`: The unique identifier of the lien. - `walletNumber`: The wallet number associated with the lien. - `lienAmount`: The amount of money that is held as a lien. - `lienStartDate`: The date and time when the lien was initiated. - `lienReference`: A reference code associated with the lien. - `lienCurrency`: The currency of the lien amount. - `validUntil`: The date until which the lien is valid. - `eventLienAmount`: The amount of money involved in the lien event. - `lienRemarks`: Additional remarks or notes about the lien. - `isActive`: Indicates whether the lien is currently active or not. - `transactionType`: The type of transaction associated with the lien. - `requestedBy`: The entity that requested the lien. - `createdAt`: The date and time when the lien was created. - `updatedAt`: The date and time when the lien was last updated. - `walletId`: The unique identifier of the wallet associated with the lien. - `clientWallet`: Information about the client's wallet, if applicable. - `currentPage`: The current page number of the returned results. - `pageSize`: The number of results per page. - `totalCount`: The total number of liens. - `totalPages`: The total number of pages based on the page size and total count. ### Example: ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "liens": [ { "id": 123456, "walletNumber": "90010000298", "lienAmount": 50000, "lienStartDate": "2023-10-03T00:00:00", "lienReference": "045dc99be7d046ddb8a6efd829955b75169636455210030822485459c01de44b65b8b174f12dd74aa5", "lienCurrency": "NGN", "validUntil": "2023-10-04T00:00:00", "eventLienAmount": 0, "lienRemarks": "Property Deposit", "isActive": true, "transactionType": "Deposit", "requestedBy": "chinedu@passpoint.com", "createdAt": "2023-10-03T20:22:32.8780785", "updatedAt": "2023-10-03T20:22:32.8780786", "walletId": "a35c8a28-2590-415e-8864-08dbc040c6a2", "clientWallet": "Client Wallet ABC123" } ], "currentPage": 1, "pageSize": 10, "totalCount": 1, "totalPages": 1 } ```
    • [Add Lien](https://docs.miden.co/wallet-as-a-service/transactions/lien/add-lien.md): This endpoint allow clients to add a new lien to an account.
    • [Advice](https://docs.miden.co/wallet-as-a-service/transactions/lien/advice.md): This endpoint allow clients to provide advisory notes or comments related to specific liens.
    • [Update](https://docs.miden.co/wallet-as-a-service/transactions/lien/update.md): This endpoint allow clients to Update existing lien details.
    • [Unblock & Debit Instant](https://docs.miden.co/wallet-as-a-service/transactions/lien/unblock-and-debit-instant.md): This endpoint allow clients to unblock and debit an account related to a lien.
    • [Unblock & Debit Async](https://docs.miden.co/wallet-as-a-service/transactions/lien/unblock-and-debit-async.md): This endpoint allow clients to Trigger an asynchronous unblocking and debit process on a customers account
  • [All Posted Transactions Paginated](https://docs.miden.co/wallet-as-a-service/transactions/all-posted-transactions-paginated.md): #### **Description:** This endpoint retrieves a comprehensive list of all previously posted transactions in a paginated manner. #### **Usage:** Retrieve a list of posted transactions within the system, with pagination. #### **Request URL:** ``` /api/v1/transactions/all?PageNumber=1&PageSize=20&WalletNumber=90010000289 ``` #### **Response Body:** ``` json { "transactions": [ { "id": 123456, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M8", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "runningBalance": 0, "valueDate": "2023-09-30T00:00:00", "isReversed": true, "reversalDate": "2023-09-30T11:27:10.3137665", "transactionType": "WalletFunding", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T11:23:36.0239307", "postedBy": "System", "transactionReference": "FUNWALf4a31f10767a4bf092386d78d388df4c169607301509301123" } ], "currentPage": 1, "pageSize": 20, "totalPages": 1, "totalCount": 1, "isSuccessful": true, "responseMessage": "Request Successful", "responseCode": "000" } ``` #### **Response Body Explanation:** - `transactions`: An array containing information about each posted transaction. - `id`: The unique identifier for the transaction. - `walletNumber`: The wallet number associated with the transaction. - `transactionDate`: The date and time of the transaction. - `transactionId`: The ID of the transaction. - `partTransactionSerialNumber`: The serial number of the transaction. - `partTransactionType`: The type of transaction. - `transactionAmount`: The amount of the transaction. - `transactionCurrency`: The currency of the transaction. - `narration`: The description or narration of the transaction. - `runningBalance`: The running balance after the transaction. - `valueDate`: The date value of the transaction. - `isReversed`: Indicates if the transaction is reversed. - `reversalDate`: The date and time of the reversal, if applicable. - `transactionType`: The type of transaction. - `walletName`: The name of the wallet associated with the transaction. - `status`: The status of the transaction. - `enteredBy`: The user who entered the transaction. - `createdAt`: The date and time the transaction was created. - `postedBy`: The entity that posted the transaction. - `transactionReference`: The reference code for the transaction. - `currentPage`: The current page of the pagination. - `pageSize`: The number of transactions per page. - `totalPages`: The total number of pages available. - `totalCount`: The total number of transactions. - `isSuccessful`: Indicates whether the request was successful. - `responseMessage`: A message indicating the status of the request. - `responseCode`: A code indicating the status of the request. #### Example**:** ``` json { "transactions": [ { "id": 123456, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M8", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "runningBalance": 0, "valueDate": "2023-09-30T00:00:00", "isReversed": true, "reversalDate": "2023-09-30T11:27:10.3137665", "transactionType": "WalletFunding", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T11:23:36.0239307", "postedBy": "System", "transactionReference": "FUNWALf4a31f10767a4bf092386d78d388df4c169607301509301123" } ], "currentPage": 1, "pageSize": 20, "totalPages": 1, "totalCount": 1, "isSuccessful": true, "responseMessage": "Request Successful", "responseCode": "000" } ```
  • [All Posted Transactions](https://docs.miden.co/wallet-as-a-service/transactions/all-posted-transactions.md): #### **Description:** This endpoint retrieves a comprehensive list of all previously posted transactions within the system. #### **Usage:** Retrieve a list of all posted transactions within the system. #### **Request URL:** ``` /api/v1/transactions/all-download?TransactionId=M21 ``` #### **Response Body:** ``` json { "transactions": [ { "id": 123456, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M8", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "runningBalance": 0, "valueDate": "2023-09-30T00:00:00", "isReversed": true, "reversalDate": "2023-09-30T11:27:10.3137665", "transactionType": "WalletFunding", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T11:23:36.0239307", "postedBy": "System", "transactionReference": "FUNWALf4a31f10767a4bf092386d78d388df4c169607301509301123" } ], "currentPage": 0, "pageSize": 0, "totalPages": 0, "totalCount": 0, "isSuccessful": true, "responseMessage": "Request Successful", "responseCode": "000" } ``` #### **Response Body Explanation:** - `transactions`: An array containing information about each posted transaction. - `id`: The unique identifier for the transaction. - `walletNumber`: The wallet number associated with the transaction. - `transactionDate`: The date and time of the transaction. - `transactionId`: The ID of the transaction. - `partTransactionSerialNumber`: The serial number of the transaction. - `partTransactionType`: The type of transaction. - `transactionAmount`: The amount of the transaction. - `transactionCurrency`: The currency of the transaction. - `narration`: The description or narration of the transaction. - `runningBalance`: The running balance after the transaction. - `valueDate`: The date value of the transaction. - `isReversed`: Indicates if the transaction is reversed. - `reversalDate`: The date and time of the reversal, if applicable. - `transactionType`: The type of transaction. - `walletName`: The name of the wallet associated with the transaction. - `status`: The status of the transaction. - `enteredBy`: The user who entered the transaction. - `createdAt`: The date and time the transaction was created. - `postedBy`: The entity that posted the transaction. - `transactionReference`: The reference code for the transaction. - `currentPage`: The current page of the pagination. - `pageSize`: The number of transactions per page. - `totalPages`: The total number of pages available. - `totalCount`: The total number of transactions. - `isSuccessful`: Indicates whether the request was successful. - `responseMessage`: A message indicating the status of the request. - `responseCode`: A code indicating the status of the request. #### **Examples**: ``` json { "transactions": [ { "id": 123456, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M8", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "runningBalance": 0, "valueDate": "2023-09-30T00:00:00", "isReversed": true, "reversalDate": "2023-09-30T11:27:10.3137665", "transactionType": "WalletFunding", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T11:23:36.0239307", "postedBy": "System", "transactionReference": "FUNWALf4a31f10767a4bf092386d78d388df4c169607301509301123" } ], "currentPage": 0, "pageSize": 0, "totalPages": 0, "totalCount": 0, "isSuccessful": true, "responseMessage": "Request Successful", "responseCode": "000" } ```
  • [Wallet Statement](https://docs.miden.co/wallet-as-a-service/transactions/wallet-statement.md): #### **Description:** This endpoint retrieves the statement of transactions for a specific wallet. #### **Usage:** Use this endpoint to retrieve a list of transactions associated with a particular wallet. #### **Request URL:** ``` /api/v1/transactions/view-download?WalletNumber=90010000289&StartDate=2023-10-04&EndDate=2023-10-04 ``` #### Response Body: ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "transactions": [ { "id": 6, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M3", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 2000000, "transactionCurrency": "NGN", "narration": "Sandbox funding", "narration2": null, "runningBalance": 2000000, "valueDate": "2023-07-19T00:00:00", "isReversed": false, "reversalDate": null, "transactionType": "Transfer", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T07:40:45.4468362", "postedBy": "System", "updatedAt": "2023-09-30T07:40:45.44849", "formattedAmount": 2000000, "thirdPartyTransactionReference": "", "transactionReference": "POSTc7170b03c3aa4ca3893d7fff6da9e2ea169605964509300740" }, { "id": 8, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M4", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 300, "transactionCurrency": "NGN", "narration": "Test Transaction", "narration2": null, "runningBalance": 2000300, "valueDate": "2022-06-03T00:00:00", "isReversed": false, "reversalDate": null, "transactionType": "Transfer", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T07:45:19.5776711", "postedBy": "System", "updatedAt": "2023-09-30T07:45:19.5791385", "formattedAmount": 300, "thirdPartyTransactionReference": null, "transactionReference": null }, { "id": 10, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M5", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "narration2": null, "runningBalance": 2050300, "valueDate": "2023-07-17T00:00:00", "isReversed": false, "reversalDate": null, "transactionType": "WalletFunding", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T07:45:37.9012642", "postedBy": "System", "updatedAt": "2023-09-30T07:45:37.9019855", "formattedAmount": 50000, "thirdPartyTransactionReference": "", "transactionReference": "FUNWAL1d834301565a405cbc8f8d5ac379b582169605993709300745" }, { "id": 12, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M6", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 100000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 100000 - Test Funding", "narration2": null, "runningBalance": 2150300, "valueDate": "2023-07-17T00:00:00", "isReversed": false, "reversalDate": null, "transactionType": "WalletFunding", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T07:45:59.6183573", "postedBy": "System", "updatedAt": "2023-09-30T07:45:59.619254", "formattedAmount": 100000, "thirdPartyTransactionReference": "", "transactionReference": "FUNWAL2bd40c98bb154346bfc40d5c219270f1169605995909300745" }, { "id": 13, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M7", "partTransactionSerialNumber": 1, "partTransactionType": "D", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Debit Request 50000 - Test Debit", "narration2": null, "runningBalance": 2100300, "valueDate": "2023-07-17T00:00:00", "isReversed": false, "reversalDate": null, "transactionType": "DebitRequest", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T07:46:35.8309448", "postedBy": "System", "updatedAt": "2023-09-30T07:46:35.8320964", "formattedAmount": -50000, "thirdPartyTransactionReference": "", "transactionReference": "DEBITWAL1b003167ec874b9dafe21e25ccf5a611169605999509300746" }, { "id": 16, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M8", "partTransactionSerialNumber": 2, "partTransactionType": "C", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "narration2": null, "runningBalance": 2150300, "valueDate": "2023-09-30T00:00:00", "isReversed": true, "reversalDate": "2023-09-30T11:27:10.3137665", "transactionType": "WalletFunding", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T11:23:36.0239307", "postedBy": "System", "updatedAt": "2023-09-30T11:27:10.3137666", "formattedAmount": 50000, "thirdPartyTransactionReference": "", "transactionReference": "FUNWALf4a31f10767a4bf092386d78d388df4c169607301509301123" }, { "id": 17, "walletNumber": "90010000001", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M9", "partTransactionSerialNumber": 1, "partTransactionType": "D", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "REV Wallet Funding of 50000 - Test Funding", "narration2": null, "runningBalance": 2100300, "valueDate": "0001-01-01T00:00:00", "isReversed": false, "reversalDate": null, "transactionType": "WalletFunding", "walletName": "Sixteen Hundreds Solutions (NGN)", "status": "P", "enteredBy": "chinedu@passpoint.com", "createdAt": "2023-09-30T11:27:10.3118849", "postedBy": "System", "updatedAt": "2023-09-30T11:27:10.3130521", "formattedAmount": -50000, "thirdPartyTransactionReference": null, "transactionReference": "REVFUNWALf4a31f10767a4bf092386d78d388df4c169607301509301123" } ] } ``` #### Request Body Explantion: - **isSuccessful**: This field indicates whether the request was successful or not. In this case, it is set to `true`, meaning the request was successful. - **responseCode**: This is a code associated with the response. In this example, it's "000," which typically signifies success. Other codes may represent different outcomes like errors or warnings - **responseMessage**: This field provides a message corresponding to the response code. In this case, it states "Request Successful," confirming the success of the request. - **transactions**: This is an array containing multiple transaction objects. Each transaction object represents a financial transaction associated with the specified wallet. \- **id**: Unique identifier for the transaction. \- walletNumber**: The wallet number associated with the transaction.**\- transactionDate**: Date and time when the transaction occurred.****\- transactionId**: Identifier for the transaction. **\- partTransactionSerialNumber**: Serial number for part of the transaction (if applicable). **\- partTransactionType**: Indicates whether it's a credit ("C") or debit ("D") transaction. **\- transactionAmount**: The amount of the transaction. **\- transactionCurrency**: The currency of the transaction. **\- narration**: Description or reason for the transaction. **\- narration2**: Additional description or details for the transaction. **\- runningBalance**: The running balance of the wallet after the transaction. **\- valueDate**: Date when the transaction value is credited or debited. **\- isReversed**: Indicates if the transaction is reversed (`true` or `false`). **\- reversalDate**: Date and time when the transaction was reversed (if applicable). **\- transactionType**: Type of transaction (e.g., Transfer, Purchase, Salary). **\- walletName**: Name of the wallet associated with the transaction. **\- status**: Current status of the transaction (e.g., Pending, Completed). **\- enteredBy**: Email or identifier of the user who initiated the transaction. **\- createdAt**: Date and time when the transaction was created. **\- postedBy**: Entity responsible for posting the transaction (e.g., System). **\- updatedAt**: Date and time when the transaction was last updated. **\- formattedAmount**: The transaction amount formatted for display. **\- thirdPartyTransactionReference**: Reference to a third-party transaction (if applicable). **transactionReference**: Reference code for the transaction. #### **Example:** ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "transactions": [ { "id": 6, "walletNumber": "90010000001", "transactionDate": "2023-09-30T10:15:27", "transactionId": "M3", "partTransactionSerialNumber": 2, "partTransactionType": "Credit", "transactionAmount": 2000000, "transactionCurrency": "NGN", "narration": "Funding from Company XYZ", "narration2": null, "runningBalance": 2000000, "valueDate": "2023-09-30T10:15:27", "isReversed": false, "reversalDate": null, "transactionType": "Transfer", "walletName": "Nomi's Wallet", "status": "Pending", "enteredBy": "nomi@miden.com", "createdAt": "2023-09-30T10:15:27", "postedBy": "System", "updatedAt": "2023-09-30T10:15:27", "formattedAmount": 2000000, "thirdPartyTransactionReference": "", "transactionReference": "POSTc7170b03c3aa4ca3893d7fff6da9e2ea169605964509300740" }, { "id": 8, "walletNumber": "90010000001", "transactionDate": "2023-09-30T14:20:45", "transactionId": "M4", "partTransactionSerialNumber": 2, "partTransactionType": "Credit", "transactionAmount": 300, "transactionCurrency": "NGN", "narration": "Product Purchase - Online Store ABC", "narration2": null, "runningBalance": 2000300, "valueDate": "2023-09-30T14:20:45", "isReversed": false, "reversalDate": null, "transactionType": "Purchase", "walletName": "Nomi's Wallet", "status": "Completed", "enteredBy": "nomi@miden.com", "createdAt": "2023-09-30T14:20:45", "postedBy": "System", "updatedAt": "2023-09-30T14:20:45", "formattedAmount": 300, "thirdPartyTransactionReference": null, "transactionReference": null }, { "id": 10, "walletNumber": "90010000001", "transactionDate": "2023-09-30T15:45:12", "transactionId": "M5", "partTransactionSerialNumber": 2, "partTransactionType": "Credit", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Salary Deposit - Company ABC", "narration2": null, "runningBalance": 2050300, "valueDate": "2023-09-30T15:45:12", "isReversed": false, "reversalDate": null, "transactionType": "Salary", "walletName": "Nomi's Wallet", "status": "Completed", "enteredBy": "nomi@miden.com", "createdAt": "2023-09-30T15:45:12", "postedBy": "System", "updatedAt": "2023-09-30T15:45:12", "formattedAmount": 50000, "thirdPartyTransactionReference": "", "transactionReference": "FUNWAL1d834301565a405cbc8f8d5ac379b582169605993709300745" }, { "id": 12, "walletNumber": "90010000001", "transactionDate": "2023-09-30T16:30:55", "transactionId": "M6", "partTransactionSerialNumber": 2, "partTransactionType": "Credit", "transactionAmount": 100000, "transactionCurrency": "NGN", "narration": "Bonus Payment", "narration2": null, "runningBalance": 2150300, "valueDate": "2023-09-30T16:30:55", "isReversed": false, "reversalDate": null, "transactionType": "Bonus", "walletName": "Nomi's Wallet", "status": "Completed", "enteredBy": "nomi@miden.com", "createdAt": "2023-09-30T16:30:55", "postedBy": "System", "updatedAt": "2023-09-30T16:30:55", "formattedAmount": 100000, "thirdPartyTransactionReference": "", "transactionReference": "FUNWAL2bd40c98bb154346bfc40d5c219270f1169605995909300745" }, { "id": 13, "walletNumber": "90010000001", "transactionDate": "2023-09-30T18:00:22", "transactionId": "M7", "partTransactionSerialNumber": 1, "partTransactionType": "Debit", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Rent Payment", "narration2": null, "runningBalance": 2100300, "valueDate": "2023-09-30T18:00:22", "isReversed": false, "reversalDate": null, "transactionType": "Rent", "walletName": "Nomi's Wallet", "status": "Completed", "enteredBy": "nomi@miden.com", "createdAt": "2023-09-30T18:00:22", "postedBy": "System", "updatedAt": "2023-09-30T18:00:22", "formattedAmount": -50000, "thirdPartyTransactionReference": "", "transactionReference": "DEBITWAL1b003167ec874b9dafe21e25ccf5a611169605999509300746" }, { "id": 16, "walletNumber": "90010000001", "transactionDate": "2023-09-30T20:30:10", "transactionId": "M8", "partTransactionSerialNumber": 2, "partTransactionType": "Credit", "transactionAmount": 50000 "transactionCurrency": "NGN", "narration": "Refund from Online Purchase", "narration2": null, "runningBalance": 2150300, "valueDate": "2023-09-30T20:30:10", "isReversed": true, "reversalDate": "2023-09-30T21:15:40", "transactionType": "Refund", "walletName": "Nomi's Wallet", "status": "Completed", "enteredBy": "nomi@miden.com", "createdAt": "2023-09-30T20:30:10", "postedBy": "System", "updatedAt": "2023-09-30T21:15:40", "formattedAmount": 50000, "thirdPartyTransactionReference": "", "transactionReference": "REFUNDWALf4a31f10767a4bf092386d78d388df4c169607301509301123" }, { "id": 17, "walletNumber": "90010000001", "transactionDate": "2023-09-30T22:00:00", "transactionId": "M9", "partTransactionSerialNumber": 1, "partTransactionType": "Debit", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Utility Bill Payment", "narration2": null, "runningBalance": 2100300, "valueDate": "2023-09-30T22:00:00", "isReversed": false, "reversalDate": null, "transactionType": "Utility", "walletName": "Nomi's Wallet", "status": "Completed", "enteredBy": "nomi@miden.com", "createdAt": "2023-09-30T22:00:00", "postedBy": "System", "updatedAt": "2023-09-30T22:00:00", "formattedAmount": -50000, "thirdPartyTransactionReference": null, "transactionReference": "DEBITWALf4a31f10767a4bf092386d78d388df4c169607301509301123" } ] } ```
  • [Value Dated Transactions Paginated](https://docs.miden.co/wallet-as-a-service/transactions/value-dated-transactions-paginated.md): #### Description: This endpoint retrieves a paginated list of value-dated transactions. Value-dated transactions are those that have an effective date set in the future. #### Usage: You can use this endpoint to fetch value-dated transactions in batches, allowing for efficient retrieval and processing of future transactions. #### Request URL: ``` /api/v1/transactions/value-dated?PageNumber=1&PageSize=20 ``` #### Response Body: ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "transactions": [ { "id": 1, "walletNumber": "90010000001", "walletName": "Sixteen Hundreds Solutions (NGN)", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M10", "partTransactionType": "Credit", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "valueDate": "2023-10-01T00:00:00", "transactionType": "WalletFunding", "transactionStatus": "Uncleared", "thirdPartyTransactionReference": null, "cleared": false, "createdAt": "2023-09-30T11:39:54.8452786", "updatedAt": null } ], "currentPage": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } ``` #### Request Body Explanation: - `isSuccessful`: Indicates whether the request was successful. - `responseCode`: A code indicating the status of the response. - `responseMessage`: A message describing the status of the response. - `transactions`: An array containing information about the retrieved transactions. - `id`: Unique identifier for the transaction. - `walletNumber`: The wallet number associated with the transaction. - `walletName`: The name of the wallet associated with the transaction. - `transactionDate`: The date and time of the transaction. - `transactionId`: The identifier for the transaction. - `partTransactionType`: The type of transaction (e.g., Credit or Debit). - `transactionAmount`: The amount of the transaction. - `transactionCurrency`: The currency of the transaction. - `narration`: A description or reason for the transaction. - `valueDate`: The effective date of the transaction. - `transactionType`: The type of transaction (e.g., Wallet Funding or Transfer). - `transactionStatus`: The status of the transaction (e.g., Cleared or Uncleared). - `thirdPartyTransactionReference`: A reference to a third-party transaction if applicable. - `cleared`: Indicates whether the transaction has been cleared. - `createdAt`: The date and time when the transaction was created. - `updatedAt`: The date and time when the transaction was last updated. - `currentPage`: The current page number of the returned results. - `pageSize`: The number of transactions per page. - `totalCount`: The total number of transactions matching the query criteria. - `totalPages`: The total number of pages based on the specified page size. #### Example: ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "transactions": [ { "id": 1, "walletNumber": "90010000001", "walletName": "Sixteen Hundreds Solutions (NGN)", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M10", "partTransactionType": "Credit", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "valueDate": "2023-10-01T00:00:00", "transactionType": "WalletFunding", "transactionStatus": "Uncleared", "thirdPartyTransactionReference": null, "cleared": false, "createdAt": "2023-09-30T11:39:54.8452786", "updatedAt": null } ], "currentPage": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } ```
  • [Value Dated Transactions](https://docs.miden.co/wallet-as-a-service/transactions/value-dated-transactions.md): #### Description: This endpoint allows you to retrieve a list of transactions with value dates set in the future. #### Usage: You can use this endpoint to fetch upcoming transactions that are scheduled to occur on future dates. #### Request URL: ``` /api/v1/transactions/value-dated-download?Cleared=false ``` #### Response Body: ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "transactions": [ { "id": 1, "walletNumber": "90010000001", "walletName": "Sixteen Hundreds Solutions (NGN)", "transactionDate": "2023-09-30T00:00:00", "transactionId": "M10", "partTransactionType": "C", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Wallet Funding of 50000 - Test Funding", "valueDate": "2023-10-01T00:00:00", "transactionType": "WalletFunding", "transactionStatus": "Uncleared", "thirdPartyTransactionReference": null, "cleared": false, "createdAt": "2023-09-30T11:39:54.8452786", "updatedAt": null } ], "currentPage": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } ``` #### Response Body Explanation: - **isSuccessful**: Indicates whether the request was successful or not. - **responseCode**: A code indicating the outcome of the request. - **responseMessage**: A message providing additional information about the outcome of the request. - **transactions**: An array containing information about the retrieved transactions. - **id**: The unique identifier for the transaction. - **walletNumber**: The wallet number associated with the transaction. - **walletName**: The name of the wallet associated with the transaction. - **transactionDate**: The date and time when the transaction occurred. - **transactionId**: A unique identifier for the transaction. - **partTransactionType**: Indicates whether the transaction is a credit (C) or a debit (D). - **transactionAmount**: The amount of the transaction. - **transactionCurrency**: The currency of the transaction. - **narration**: A description or reason for the transaction. - **valueDate**: The date when the transaction will take effect or become valuable. - **transactionType**: The type of transaction (e.g., WalletFunding). - **transactionStatus**: The status of the transaction (e.g., Uncleared). - **thirdPartyTransactionReference**: A reference to a third-party system or transaction. - **cleared**: Indicates whether the transaction has been cleared. - **createdAt**: The date and time when the transaction record was created. - **updatedAt**: The date and time when the transaction record was last updated. - **currentPage**: The current page number of the retrieved transactions. - **pageSize**: The number of transactions included per page. - **totalCount**: The total number of transactions available. - **totalPages**: The total number of pages based on the pageSize. #### Example: ``` json { "isSuccessful": true, "responseCode": "000", "responseMessage": "Request Successful", "transactions": [ { "id": 1, "walletNumber": "90010000001", "walletName": "Nomi's Wallet", "transactionDate": "2023-09-30T08:15:30", "transactionId": "M10", "partTransactionType": "Credit", "transactionAmount": 50000, "transactionCurrency": "NGN", "narration": "Salary Deposit", "valueDate": "2023-10-01T00:00:00", "transactionType": "Salary", "transactionStatus": "Uncleared", "thirdPartyTransactionReference": null, "cleared": false, "createdAt": "2023-09-30T11:39:54.8452786", "updatedAt": null } ], "currentPage": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } ```
  • [Create Transaction](https://docs.miden.co/wallet-as-a-service/transactions/create-transaction.md): This endpoint allow clients to Initiate the creation of a new transaction, facilitating various financial operations.
  • [Reverse Transaction](https://docs.miden.co/wallet-as-a-service/transactions/reverse-transaction.md): This endpoint allow clients to Trigger a reversal process for a previous transaction, correcting errors or unintended transactions.
  • [Funds Transfer](https://docs.miden.co/wallet-as-a-service/transactions/funds-transfer.md): This endpoint allow clients to initiate the transfer of funds between accounts or entities, supporting various financial transactions.
  • [Bulk Posting Json](https://docs.miden.co/wallet-as-a-service/transactions/bulk-posting-json.md): This endpoint allow clients to initiate the transfer of funds between accounts or entities, supporting various financial transactions.
  • [Bulk Posting File](https://docs.miden.co/wallet-as-a-service/transactions/bulk-posting-file.md): This endpoint allow clients to initiate the transfer of funds between accounts or entities, supporting various financial transactions.
  • [Fund Wallet](https://docs.miden.co/wallet-as-a-service/transactions/fund-wallet.md): Description: The FUND WALLET endpoint enables clients to credit funds to a specified wallet within the system. Usage: This endpoint facilitates seamless transactions by allowing users to specify the wallet to be credited, the transaction amount, currency, etc, increasing its balance to accommodate financial operations. Endpoint: Plain Text /api/v1/transactions/fund-wallet Request Body: Field Name Field Description Field Type Is Mandatory Example creditWalletNumber The wallet number to be credited String Yes “5001000265” transactionAmount The amount to be credited to the wallet String Yes “11000” transactionCurrency The currency of the transaction String Yes “USD” transactionRef Unique reference for the transaction String Yes “12gtap234” narration Description or reason for the transaction String No “Test Funding” enteredBy The entity initiating the transaction String No “System” valueDate Date when the transaction value is recorded String No “2024-04-03” chargeAmount Any charges associated with the transaction String No “0” transactionType Type of transaction (e.g., WalletFunding) String Yes “WalletFunding”
  • [Debit Wallet](https://docs.miden.co/wallet-as-a-service/transactions/debit-wallet.md): This endpoint allow clients to fund a specific wallet, increasing its balance to accommodate financial operations.
  • [Funds Transfer Cross Currency](https://docs.miden.co/wallet-as-a-service/transactions/funds-transfer-cross-currency.md): This endpoint allow clients to execute funds transfer between wallets with differing currencies, often involving currency conversion.
  • [Currency Conversion](https://docs.miden.co/wallet-as-a-service/transactions/currency-conversion.md): This endpoint allow clients to perform currency conversion operations, facilitating transactions involving different currencies.
  • [Regularize Value Dated Transactions](https://docs.miden.co/wallet-as-a-service/transactions/regularize-value-dated-transactions.md): This endpoint allow clients to perform currency conversion operations, facilitating transactions involving different currencies.
• [Card Withdrawal (copy+1)](https://docs.miden.co/card-withdrawal-copy-1.md): ### **Description** Withdraws funds from a card and returns them to the linked wallet. This operation debits the specified amount from the card and credits it back to the wallet. It is typically used when funds need to be moved off a card after funding, reallocation, or operational correction. Cards must maintain the required minimum balance after withdrawal. ### **Usage** Use this endpoint to: * move funds from a card back to a wallet * reduce the balance on a card that is no longer needed or that cardholder owes you. * correct funding errors * recover unused funds from a card This is a **card → wallet** operation.
• [Card Transaction Status (copy+1)](https://docs.miden.co/card-transaction-status-copy-1.md): ### **Description** Retrieves the current status and details of a specific card transaction using its transaction reference. This endpoint returns a single transaction record, including the transaction type, status, amount, merchant details, card identifiers, and related authorization metadata. It is useful for checking the outcome of a previously initiated transaction without retrieving the full transaction list. ### **Usage** Use this endpoint to: * Check the status of a specific transaction using its reference * Confirm whether a transaction is pending, successful, declined, or otherwise processed * Investigate transaction details for support, reconciliation, or operational review * Retrieve merchant, amount, and card information tied to a known transaction * Track the outcome of card funding, withdrawals, authorizations, and other card operations This endpoint is best used when you already have a `transactionReference` and need the details for that single transaction.
• [Card Transaction Status (copy+2)](https://docs.miden.co/card-transaction-status-copy-2.md): ### **Description** Retrieves the current status and details of a specific card transaction using its transaction reference. This endpoint returns a single transaction record, including the transaction type, status, amount, merchant details, card identifiers, and related authorization metadata. It is useful for checking the outcome of a previously initiated transaction without retrieving the full transaction list. ### **Usage** Use this endpoint to: * Check the status of a specific transaction using its reference * Confirm whether a transaction is pending, successful, declined, or otherwise processed * Investigate transaction details for support, reconciliation, or operational review * Retrieve merchant, amount, and card information tied to a known transaction * Track the outcome of card funding, withdrawals, authorizations, and other card operations This endpoint is best used when you already have a `transactionReference` and need the details for that single transaction.
• [Card TopUp (copy+1)](https://docs.miden.co/card-topup-copy-1.md): This Endpoint to topup / updates a user's card balance by adding a specified amount of funds to it.
• [Card TopUp (copy+1)](https://docs.miden.co/card-topup-copy-1-1.md): This Endpoint to topup / updates a user's card balance by adding a specified amount of funds to it.
• [Event Types & Event Class](https://docs.miden.co/webhooks/event-types-and-event-class.md): Complete Guide Overview In Miden webhooks, every event is defined using two key attributes: eventType eventClass These two fields work together to describe what happened and how it should be categorized , but they serve very different purposes. Understanding the distinction is critical for: Correct webhook routing Business logic implementation System design and scalability 1. What is an Event Type? Definition eventType is the most specific identifier of an event. It describes: The exact action The stage of the lifecycle The outcome (if applicable) Think of it as: “What exactly happened?” Structure of Event Type Event types follow a structured naming convention: <domain>.<entity>.<action>.<status> Example purchase.card.auth.settled Breakdown: Segment Meaning purchase Domain (transaction-related) card Entity auth Action (authorization) settled Final state Characteristics Highly granular Used for exact event handling Drives business logic decisions Can have multiple variations for the same flow Examples Across Flows Authorization Lifecycle purchase.card.auth.approved purchase.card.auth.declined purchase.card.auth.settled purchase.card.auth.reversal.settled purchase.card.auth.reversal.issuerexpiration Refund Lifecycle purchase.card.return.auth.approved purchase.card.return.auth.settled purchase.card.terminated.refund.settled Card Lifecycle purchase.card.issued purchase.card.expiration purchase.card.expiration.terminate Specialized Events purchase.card.cross-border.settled purchase.card.cross-border.pending purchase.card.cross-border.reversal purchase.card.contactless-payment.settled purchase.card.contactless-payment.pending purchase.card.contactless.activation Key Insight eventType is what you use when writing logic. Example: IF eventType == "purchase.card.auth.declined" → notify user → log failure 2. What is an Event Class? Definition eventClass is a high-level category of events. It groups related eventTypes into logical buckets. Think of it as: “What kind of event is this broadly?” Purpose Simplifies event grouping Enables coarse filtering Helps with analytics & reporting Useful for generic handlers Characteristics Less granular than eventType Represents business category Multiple eventTypes can share one eventClass Stable compared to eventType variations Examples Event Class Meaning Settlement Financial completion events CardBlock Card restriction actions RefundSettlement Refund-related settlements CrossBorder International transaction events ContactlessPayment Tap-to-pay related events ContactlessCardActivation Activation via contactless VerifyCard Card/account verification CardWithdrawal Balance deduction CardTopUp Balance addition CardExpiration Expiry lifecycle Purchase Card issuance / usage Example Mapping eventType eventClass purchase.card.auth.settled Settlement purchase.card.auth.declined Settlement purchase.card.return.auth.settled Settlement purchase.card.cross-border.settled CrossBorder purchase.card.contactless-payment.settled ContactlessPayment purchase.card.issued Purchase VerifyCardAccount VerifyCard Key Insight eventClass is what you use for grouping and routing. Example: IF eventClass == "Settlement" → update ledger → reconcile balances 3. Event Type vs Event Class (Side-by-Side) Aspect eventType eventClass Level Detailed High-level Purpose Exact behavior Categorization Granularity Very high Moderate Stability Can vary often More stable Usage Business logic Routing / grouping Example purchase.card.auth.settled Settlement 4. How They Work Together Every webhook contains both fields because they serve different layers of decision-making . Layered Handling Approach 1 Class-level filtering IF eventClass == "Settlement" 2 Type-level execution IF eventType == "purchase.card.auth.settled" → finalize transaction ELSE IF eventType == "purchase.card.return.auth.settled" → process refund 5. Best Practices Always prioritize eventType for logic eventClass alone is too broad. Use eventClass for routing pipelines Example: Send all Settlement events to finance service Send all CardBlock events to risk system Expect multiple eventTypes per flow Example: pending → approved → settled → reversed Design for extensibility New eventTypes may be added without changing eventClass. Combine both for clarity IF eventClass == "CrossBorder" AND eventType == "purchase.card.cross-border.pending" → mark as pending liability Common Pitfalls ❌ Treating eventClass as unique Multiple different actions share the same class. ❌ Ignoring alternate eventTypes Some events have paired types : settled vs pending approved vs declined activation vs failure ❌ Hardcoding only one eventType Always anticipate future variants. Final Understanding eventType = exact event (precision) eventClass = event category (context) Together, they provide: Full clarity of the event Scalable system design Clean separation of concerns