{ "openapi": "3.1.0", "info": { "title": "Sudo Sandbox API", "version": "1.0" }, "servers": [{ "url": "https://api.sandbox.sudo.cards" }], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "in": "header", "name": "Authorization", "x-bearer-format": "bearer", "x-default": "{{APIKey}}" } } }, "security": [{ "sec0": [] }], "paths": { "/customers": { "post": { "summary": "Create Customer", "description": "Creates a new customer.", "operationId": "create-customer", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["type", "name", "phoneNumber", "status", "billingAddress"], "properties": { "type": { "type": "string", "description": "This is the customer type.", "default": "individual", "enum": ["individual", "company"], "example": "individual" }, "name": { "type": "string", "description": "The customer's full name.", "example": "Jane Smith" }, "phoneNumber": { "type": "string", "description": "Customer's mobile phone number in international format.", "example": "+2348012345678" }, "emailAddress": { "type": "string", "description": "Customer's email address.", "example": "jane.smith@example.com" }, "individual": { "type": "object", "description": "Individual details. Required if customer type is `individual`.", "required": ["firstName", "lastName", "dob"], "example": { "firstName": "Jane", "lastName": "Smith", "otherNames": "Maria", "dob": "1985-05-15", "identity": { "type": "PASSPORT", "number": "A12345678" }, "documents": { "idFrontUrl": "https://your-bucket.s3.amazonaws.com//customers//passport-front.jpg", "idBackUrl": "https://your-bucket.s3.amazonaws.com//customers//passport-back.jpg" } }, "properties": { "firstName": { "type": "string", "description": "Customer's first name.", "example": "Jane" }, "lastName": { "type": "string", "description": "Customer's last name.", "example": "Smith" }, "otherNames": { "type": "string", "description": "Customer's other names.", "example": "Maria" }, "dob": { "type": "string", "description": "Customer's date of birth in the format `YYYY/MM/DD`.", "example": "1985-05-15" }, "identity": { "type": "object", "description": "Customer's identity data.", "required": ["type", "number"], "properties": { "type": { "type": "string", "description": "Identity type.", "enum": ["BVN", "NIN", "CAC", "TIN", "PASSPORT", "VC", "DL", "RC"], "example": "PASSPORT" }, "number": { "type": "string", "description": "Identity number issued by the regulator.", "example": "A12345678" } } }, "documents": { "type": "object", "description": "Customer's KYC documents.", "properties": { "idFrontUrl": { "type": "string", "description": "ID Card front page url.", "example": "https://your-bucket.s3.amazonaws.com//customers//passport-front.jpg" }, "idBackUrl": { "type": "string", "description": "ID Card back page url.", "example": "https://your-bucket.s3.amazonaws.com//customers//passport-back.jpg" }, "incorporationCertificateUrl": { "type": "string", "description": "Company incorporation certificate url." }, "addressVerificationUrl": { "type": "string", "description": "Customer address verification document url." } } } } }, "company": { "type": "object", "description": "Company details. Required if customer type is `company`.", "required": ["name"], "properties": { "name": { "type": "string", "description": "Company name." }, "identity": { "type": "object", "description": "Company identity details.", "required": ["type", "number"], "properties": { "type": { "type": "string", "description": "Identity type.", "enum": ["BVN", "NIN", "CAC", "TIN", "PASSPORT", "VC", "DL", "RC"] }, "number": { "type": "string", "description": "Identity number issued by the regulator." } } }, "officer": { "type": "object", "description": "Company officer information.", "required": ["firstName", "lastName", "dob"], "properties": { "firstName": { "type": "string", "description": "Customer's first name." }, "lastName": { "type": "string", "description": "Customer's last name." }, "otherNames": { "type": "string", "description": "Customer's other names." }, "dob": { "type": "string", "description": "Customer's date of birth in the format `YYYY/MM/DD`." }, "identity": { "type": "object", "description": "Customer's identity data.", "required": ["type", "number"], "properties": { "type": { "type": "string", "description": "Identity type.", "enum": ["BVN", "NIN", "CAC", "TIN", "PASSPORT", "VC", "DL", "RC"] }, "number": { "type": "string", "description": "Identity number issued by the regulator." } } }, "documents": { "type": "object", "description": "Customer's KYC documents.", "properties": { "idFrontUrl": { "type": "string", "description": "ID Card front page url." }, "idBackUrl": { "type": "string", "description": "ID Card back page url." }, "incorporationCertificateUrl": { "type": "string", "description": "Company incorporation certificate url." }, "addressVerificationUrl": { "type": "string", "description": "Customer address verification document url." } } } } }, "documents": { "type": "object", "description": "Customer's KYC documents.", "properties": { "idFrontUrl": { "type": "string", "description": "ID Card front page url." }, "idBackUrl": { "type": "string", "description": "ID Card back page url." }, "incorporationCertificateUrl": { "type": "string", "description": "Company incorporation certificate url." }, "addressVerificationUrl": { "type": "string", "description": "Customer address verification document url." } } } } }, "status": { "type": "string", "description": "This is the initial status of the customer.", "default": "active", "enum": ["active", "inactive"], "example": "active" }, "billingAddress": { "type": "object", "description": "This is the billing address", "required": ["line1", "city", "state", "postalCode", "country"], "properties": { "line1": { "type": "string", "description": "Street address line 1", "example": "42 Corporate Tower, Marina" }, "line2": { "type": "string", "description": "Street Address line 2", "example": "Floor 8" }, "city": { "type": "string", "description": "City", "example": "Lagos" }, "state": { "type": "string", "description": "State", "example": "Lagos" }, "postalCode": { "type": "string", "example": "100221" }, "country": { "type": "string", "description": "Billing country", "example": "Nigeria" } } } } } } } }, "responses": { "201": { "description": "Customer created successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "status": { "type": "string", "description": "Current status of the object." }, "isApproved": { "type": "boolean", "description": "Whether the customer has passed KYC and is approved." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } }, "documents": { "type": "object", "description": "Uploaded KYC document URLs.", "properties": { "idFrontUrl": { "type": "string", "description": "URL of the front of the customer's ID document." }, "idBackUrl": { "type": "string", "description": "URL of the back of the customer's ID document." }, "addressVerificationUrl": { "type": "string", "description": "URL of the customer's address verification document." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." }, "country": { "type": "string", "description": "Country." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Customer created successfully.", "data": { "_id": "64a1b2c3d4e5f6a7b8c9d0e1", "business": "63f0a1b2c3d4e5f6a7b8c9d0", "type": "individual", "name": "John Doe", "status": "active", "isApproved": true, "phoneNumber": "+2348000000000", "emailAddress": "johndoe@example.com", "individual": { "firstName": "John", "lastName": "Doe", "otherNames": "", "dob": "1990/01/01", "identity": { "type": "BVN", "number": "22212345678" }, "documents": { "idFrontUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-front.png", "idBackUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-back.png", "addressVerificationUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/utility-bill.pdf" } }, "billingAddress": { "line1": "4 Barnawa Close", "line2": "Off Challawa Crescent", "city": "Barnawa", "state": "Kaduna", "postalCode": "800243", "country": "Nigeria" }, "createdAt": "2024-09-06T12:34:56.789Z", "updatedAt": "2024-09-06T12:34:56.789Z", "__v": 0 } } } } }, "400": { "description": "Validation error \u2014 a required field is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"individual.dob\" is required", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "get": { "summary": "Get Customers", "description": "Fetches existing customer objects according to query parameters.", "operationId": "get-customers", "parameters": [{ "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of customers to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }], "responses": { "200": { "description": "Customers fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "status": { "type": "string", "description": "Current status of the object." }, "isApproved": { "type": "boolean", "description": "Whether the customer has passed KYC and is approved." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } }, "documents": { "type": "object", "description": "Uploaded KYC document URLs.", "properties": { "idFrontUrl": { "type": "string", "description": "URL of the front of the customer's ID document." }, "idBackUrl": { "type": "string", "description": "URL of the back of the customer's ID document." }, "addressVerificationUrl": { "type": "string", "description": "URL of the customer's address verification document." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." }, "country": { "type": "string", "description": "Country." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Customers fetched successfully.", "data": [ { "_id": "64a1b2c3d4e5f6a7b8c9d0e1", "business": "63f0a1b2c3d4e5f6a7b8c9d0", "type": "individual", "name": "John Doe", "status": "active", "isApproved": true, "phoneNumber": "+2348000000000", "emailAddress": "johndoe@example.com", "individual": { "firstName": "John", "lastName": "Doe", "otherNames": "", "dob": "1990/01/01", "identity": { "type": "BVN", "number": "22212345678" }, "documents": { "idFrontUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-front.png", "idBackUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-back.png", "addressVerificationUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/utility-bill.pdf" } }, "billingAddress": { "line1": "4 Barnawa Close", "line2": "Off Challawa Crescent", "city": "Barnawa", "state": "Kaduna", "postalCode": "800243", "country": "Nigeria" }, "createdAt": "2024-09-06T12:34:56.789Z", "updatedAt": "2024-09-06T12:34:56.789Z", "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error \u2014 invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid pagination parameters.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/customers/{id}": { "get": { "summary": "Get Customer", "description": "Fetches a specific customer object. Provide the customer `_id` and the corresponding object will be returned.", "operationId": "get-customer", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the customer you wish to fetch.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Customer fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "status": { "type": "string", "description": "Current status of the object." }, "isApproved": { "type": "boolean", "description": "Whether the customer has passed KYC and is approved." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } }, "documents": { "type": "object", "description": "Uploaded KYC document URLs.", "properties": { "idFrontUrl": { "type": "string", "description": "URL of the front of the customer's ID document." }, "idBackUrl": { "type": "string", "description": "URL of the back of the customer's ID document." }, "addressVerificationUrl": { "type": "string", "description": "URL of the customer's address verification document." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." }, "country": { "type": "string", "description": "Country." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Customer fetched successfully.", "data": { "_id": "64a1b2c3d4e5f6a7b8c9d0e1", "business": "63f0a1b2c3d4e5f6a7b8c9d0", "type": "individual", "name": "John Doe", "status": "active", "isApproved": true, "phoneNumber": "+2348000000000", "emailAddress": "johndoe@example.com", "individual": { "firstName": "John", "lastName": "Doe", "otherNames": "", "dob": "1990/01/01", "identity": { "type": "BVN", "number": "22212345678" }, "documents": { "idFrontUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-front.png", "idBackUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-back.png", "addressVerificationUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/utility-bill.pdf" } }, "billingAddress": { "line1": "4 Barnawa Close", "line2": "Off Challawa Crescent", "city": "Barnawa", "state": "Kaduna", "postalCode": "800243", "country": "Nigeria" }, "createdAt": "2024-09-06T12:34:56.789Z", "updatedAt": "2024-09-06T12:34:56.789Z", "__v": 0 } } } } }, "400": { "description": "Validation error \u2014 the id is not a valid customer id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid customer id.", "data": null } } } }, "404": { "description": "No customer exists with the supplied id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Customer not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "put": { "summary": "Update Customer", "description": "Updates the specific customer by setting the values of the parameters provided. Only provided parameters will be changed.", "operationId": "update-customer", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the customer you wish to update.", "schema": { "type": "string" }, "required": true }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["type", "name", "status"], "properties": { "type": { "type": "string", "description": "This is the customer type.", "default": "individual", "enum": ["individual", "company"] }, "name": { "type": "string", "description": "The customer's full name." }, "phoneNumber": { "type": "string", "description": "Customer's mobile phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "individual": { "type": "object", "description": "Individual details. Required if customer type is `individual`.", "required": ["firstName", "lastName", "dob"], "properties": { "firstName": { "type": "string", "description": "Customer's first name." }, "lastName": { "type": "string", "description": "Customer's last name." }, "otherNames": { "type": "string", "description": "Customer's other names." }, "dob": { "type": "string", "description": "Customer's date of birth in the format `YYYY/MM/DD`." }, "identity": { "type": "object", "description": "Customer's identity data.", "required": ["type", "number"], "properties": { "type": { "type": "string", "description": "Identity type.", "enum": ["BVN", "NIN", "CAC", "TIN", "PASSPORT", "VC", "DL", "RC"] }, "number": { "type": "string", "description": "Identity number issued by the regulator." } } }, "documents": { "type": "object", "description": "Customer's KYC documents.", "properties": { "idFrontUrl": { "type": "string", "description": "ID Card front page url." }, "idBackUrl": { "type": "string", "description": "ID Card back page url." }, "incorporationCertificateUrl": { "type": "string", "description": "Company incorporation certificate url." }, "addressVerificationUrl": { "type": "string", "description": "Customer address verification document url." } } } } }, "company": { "type": "object", "description": "Company details. Required if customer type is `company`.", "required": ["name"], "properties": { "name": { "type": "string", "description": "Company name." }, "identity": { "type": "object", "description": "Company identity details.", "required": ["type", "number"], "properties": { "type": { "type": "string", "description": "Identity type.", "enum": ["BVN", "NIN", "CAC", "TIN", "PASSPORT", "VC", "DL", "RC"] }, "number": { "type": "string", "description": "Identity number issued by the regulator." } } }, "officer": { "type": "object", "description": "Company officer information.", "required": ["firstName", "lastName", "dob"], "properties": { "firstName": { "type": "string", "description": "Customer's first name." }, "lastName": { "type": "string", "description": "Customer's last name." }, "otherNames": { "type": "string", "description": "Customer's other names." }, "dob": { "type": "string", "description": "Customer's date of birth in the format `YYYY/MM/DD`." }, "identity": { "type": "object", "description": "Customer's identity data.", "required": ["type", "number"], "properties": { "type": { "type": "string", "description": "Identity type.", "enum": ["BVN", "NIN", "CAC", "TIN", "PASSPORT", "VC", "DL", "RC"] }, "number": { "type": "string", "description": "Identity number issued by the regulator." } } }, "documents": { "type": "object", "description": "Customer's KYC documents.", "properties": { "idFrontUrl": { "type": "string", "description": "ID Card front page url." }, "idBackUrl": { "type": "string", "description": "ID Card back page url." }, "incorporationCertificateUrl": { "type": "string", "description": "Company incorporation certificate url." }, "addressVerificationUrl": { "type": "string", "description": "Customer address verification document url." } } } } }, "documents": { "type": "object", "description": "Customer's KYC documents.", "properties": { "idFrontUrl": { "type": "string", "description": "ID Card front page url." }, "idBackUrl": { "type": "string", "description": "ID Card back page url." }, "incorporationCertificateUrl": { "type": "string", "description": "Company incorporation certificate url." }, "addressVerificationUrl": { "type": "string", "description": "Customer address verification document url." } } } } }, "status": { "type": "string", "description": "This is the status of the customer.", "default": "active", "enum": ["active", "inactive"] }, "metadata": { "type": "string", "description": "The customer metadata object in `key-value` pair. This can be useful for storing additional information about the customer in a structured format", "format": "json" }, "billingAddress": { "type": "object", "description": "This is the billing address of the customer.", "required": ["line1", "city", "state", "postalCode", "country"], "properties": { "line1": { "type": "string", "description": "Street address line 1" }, "line2": { "type": "string", "description": "Street Address line 2" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State" }, "postalCode": { "type": "string" }, "country": { "type": "string", "description": "Billing country" } } } } } } } }, "responses": { "200": { "description": "Customer updated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "status": { "type": "string", "description": "Current status of the object." }, "isApproved": { "type": "boolean", "description": "Whether the customer has passed KYC and is approved." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } }, "documents": { "type": "object", "description": "Uploaded KYC document URLs.", "properties": { "idFrontUrl": { "type": "string", "description": "URL of the front of the customer's ID document." }, "idBackUrl": { "type": "string", "description": "URL of the back of the customer's ID document." }, "addressVerificationUrl": { "type": "string", "description": "URL of the customer's address verification document." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." }, "country": { "type": "string", "description": "Country." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Customer updated successfully.", "data": { "_id": "64a1b2c3d4e5f6a7b8c9d0e1", "business": "63f0a1b2c3d4e5f6a7b8c9d0", "type": "individual", "name": "John Doe", "status": "inactive", "isApproved": true, "phoneNumber": "+2348000000000", "emailAddress": "johndoe@example.com", "individual": { "firstName": "John", "lastName": "Doe", "otherNames": "", "dob": "1990/01/01", "identity": { "type": "BVN", "number": "22212345678" }, "documents": { "idFrontUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-front.png", "idBackUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-back.png", "addressVerificationUrl": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/utility-bill.pdf" } }, "billingAddress": { "line1": "4 Barnawa Close", "line2": "Off Challawa Crescent", "city": "Barnawa", "state": "Kaduna", "postalCode": "800243", "country": "Nigeria" }, "createdAt": "2024-09-06T12:34:56.789Z", "updatedAt": "2024-09-07T09:15:00.000Z", "__v": 0 } } } } }, "400": { "description": "Validation error \u2014 one or more fields are invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"status\" must be one of [active, inactive]", "data": null } } } }, "404": { "description": "No customer exists with the supplied id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Customer not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/fundingsources": { "post": { "summary": "Create Funding Source", "description": "Creates a new funding source.", "operationId": "create-funding-source", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["type", "status"], "properties": { "type": { "type": "string", "description": "This is the funding source type.", "default": "default", "enum": ["default", "account", "gateway"] }, "status": { "type": "string", "description": "This is the initial status of the funding source.", "default": "active", "enum": ["active", "inactive"] }, "jitGateway": { "type": "object", "description": "Just in-time gateway details. Required if type is `gateway`.", "required": ["url", "authorizationHeader", "authorizeByDefault"], "properties": { "url": { "type": "string", "description": "Just in-time gateway url (HTTPS only)." }, "authorizationHeader": { "type": "string", "description": "Just in-time gateway authorization header." }, "authorizeByDefault": { "type": "string", "description": "Just in-time gateway timeout configuration." } } } } } } } }, "responses": { "201": { "description": "Funding source created successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "status": { "type": "string", "description": "Current status of the object." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Funding source created successfully.", "data": { "_id": "670cec9d25852ba485d74286", "business": "670cec9d25852ba485d74273", "type": "default", "status": "active", "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"type\" is required", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "get": { "summary": "Get Funding Sources", "description": "Fetches existing funding sources.", "operationId": "get-funding-sources", "responses": { "200": { "description": "Funding sources fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "status": { "type": "string", "description": "Current status of the object." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Funding sources fetched successfully.", "data": [ { "_id": "670cec9d25852ba485d74286", "business": "670cec9d25852ba485d74273", "type": "default", "status": "active", "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid pagination parameters.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/fundingsources/{id}": { "get": { "summary": "Get Funding Source", "description": "Fetches a specific funding source object. Provide the source `_id` and the corresponding object will be returned.", "operationId": "get-funding-source", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the funding source you wish to fetch.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Funding source fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "status": { "type": "string", "description": "Current status of the object." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Funding source fetched successfully.", "data": { "_id": "670cec9d25852ba485d74286", "business": "670cec9d25852ba485d74273", "type": "default", "status": "active", "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid funding source id.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Funding source not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "put": { "summary": "Update Funding Source", "description": "Updates the specific funding source by setting the values of the parameters provided.", "operationId": "update-funding-source", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the funding source you wish to update.", "schema": { "type": "string" }, "required": true }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "description": "This is the status of the funding source.", "default": "active", "enum": ["active", "inactive"] }, "jitGateway": { "type": "object", "description": "Just in-time gateway details. Required if type is `gateway`.", "required": ["url", "authorizationHeader", "authorizeByDefault"], "properties": { "url": { "type": "string", "description": "Just in-time gateway url (HTTPS only)." }, "authorizationHeader": { "type": "string", "description": "Just in-time gateway authorization header." }, "authorizeByDefault": { "type": "string", "description": "Just in-time gateway timeout configuration." } } } } } } } }, "responses": { "200": { "description": "Funding source updated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "status": { "type": "string", "description": "Current status of the object." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Funding source updated successfully.", "data": { "_id": "670cec9d25852ba485d74286", "business": "670cec9d25852ba485d74273", "type": "default", "status": "inactive", "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"status\" must be one of [active, inactive]", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Funding source not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts": { "post": { "summary": "Create Account", "description": "Creates a new account.", "operationId": "create-account", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["type", "currency", "accountType"], "properties": { "type": { "type": "string", "description": "The type of account", "default": "account", "enum": ["account", "wallet"] }, "currency": { "type": "string", "description": "The currency of the account.", "default": "NGN", "enum": ["NGN", "USD"] }, "accountType": { "type": "string", "description": "The account type.", "default": "Savings", "enum": ["Savings", "Current"] }, "customerId": { "type": "string", "description": "The id of the customer. Required when 'type' is `wallet`." } } } } } }, "responses": { "201": { "description": "Account created successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Account created successfully.", "data": { "_id": "6a26b1a448fe5e287ce408d0", "business": "696edb9889c90df3bcdbe067", "customer": "6a26b14a48fe5e287ce40899", "type": "wallet", "currency": "USD", "accountName": "John Doemain", "bankCode": "SudoHUSMC", "accountType": "Current", "accountNumber": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "currentBalance": 0, "availableBalance": 0, "provider": "SudoHUSMC", "providerReference": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "referenceCode": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "reloadable": true, "isDefault": false, "isDeleted": false, "createdAt": "2026-06-08T12:12:20.345Z", "updatedAt": "2026-06-08T12:12:20.345Z", "charges": [], "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"customerId\" is required", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "get": { "summary": "Get Accounts", "description": "Fetches existing accounts according to query parameters.", "operationId": "get-accounts", "parameters": [{ "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of accounts to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "currency", "in": "query", "description": "The currency type of the accounts you wish to fetch.", "schema": { "type": "string", "enum": ["ALL", "NGN", "USD"], "default": "ALL" } }, { "name": "type", "in": "query", "description": "Specifies whether to fetch the settlement accounts or the wallets", "schema": { "type": "string", "enum": ["account", "wallet"], "default": "account" } }], "responses": { "200": { "description": "Accounts fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Accounts fetched successfully.", "data": [ { "_id": "6a26b1a448fe5e287ce408d0", "business": "696edb9889c90df3bcdbe067", "customer": "6a26b14a48fe5e287ce40899", "type": "wallet", "currency": "USD", "accountName": "John Doemain", "bankCode": "SudoHUSMC", "accountType": "Current", "accountNumber": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "currentBalance": 0, "availableBalance": 0, "provider": "SudoHUSMC", "providerReference": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "referenceCode": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "reloadable": true, "isDefault": false, "isDeleted": false, "createdAt": "2026-06-08T12:12:20.345Z", "updatedAt": "2026-06-08T12:12:20.345Z", "charges": [], "__v": 0 }, { "_id": "6a26b18c48fe5e287ce408b4", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRIMETECH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010990188", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "6a26b18cd32eea0024e8398c", "referenceCode": "subacc_1780920715820", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-06-08T12:11:56.272Z", "updatedAt": "2026-06-08T12:11:56.272Z", "charges": [], "__v": 0 }, { "_id": "6a26a5dbcc75963954c24301", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRIMETECH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010070636", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "6a26a5dbd32eea0024e835fb", "referenceCode": "subacc_1780917722305", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-06-08T11:22:03.491Z", "updatedAt": "2026-06-08T11:22:03.491Z", "charges": [], "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid pagination parameters.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/{id}": { "get": { "summary": "Get Account", "description": "Fetches a specific account object. Provide the account `_id` and the corresponding object will be returned.", "operationId": "get-account", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the account you wish to fetch.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Account fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Account fetched successfully.", "data": { "_id": "6a26b1a448fe5e287ce408d0", "business": "696edb9889c90df3bcdbe067", "customer": "6a26b14a48fe5e287ce40899", "type": "wallet", "currency": "USD", "accountName": "John Doemain", "bankCode": "SudoHUSMC", "accountType": "Current", "accountNumber": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "currentBalance": 0, "availableBalance": 0, "provider": "SudoHUSMC", "providerReference": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "referenceCode": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe", "reloadable": true, "isDefault": false, "isDeleted": false, "createdAt": "2026-06-08T12:12:20.345Z", "updatedAt": "2026-06-08T12:12:20.345Z", "charges": [], "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid account id.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Account not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/{id}/balance": { "get": { "summary": "Get Account Balance", "description": "Fetches the balance of the specified account.", "operationId": "get-account-balance", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the account you wish to fetch the balance for.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Account balance fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." } } } } }, "example": { "statusCode": 200, "message": "Account balance fetched successfully.", "data": { "currentBalance": 18000, "availableBalance": 18000 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid account id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/{id}/transactions": { "get": { "summary": "Get Account Transactions", "description": "Fetches all transactions of the specified account according to the query parameters.", "operationId": "get-account-transactions", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the account you wish to fetch the transactions for.", "schema": { "type": "string" }, "required": true }, { "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of transactions to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "fromDate", "in": "query", "description": "This is the start date of the date range.", "schema": { "type": "string", "format": "date" } }, { "name": "toDate", "in": "query", "description": "This is the end date of the date range.", "schema": { "type": "string", "format": "date" } }], "responses": { "200": { "description": "Account transactions fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "card": { "type": "string", "description": "Associated card \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "authorization": { "type": "string", "description": "Identifier of the authorization this transaction belongs to." }, "type": { "type": "string", "description": "Type of the object." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "integer", "description": "VAT charged, in the minor currency unit." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "status": { "type": "string", "description": "Current status of the object." }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Account transactions fetched successfully.", "data": [ { "_id": "6840c1aa2b3c4d5e6f700333", "business": "670cec9d25852ba485d74273", "customer": "64a1b2c3d4e5f6a7b8c9d0e1", "card": "6418eb71a37e405064694518", "account": "67974b365c184d20fc340889", "authorization": "6840c1aa2b3c4d5e6f700222", "type": "purchase", "amount": 5000, "fee": 0, "vat": 0, "currency": "NGN", "merchantAmount": 5000, "merchantCurrency": "NGN", "status": "completed", "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "TRX-250604-2156" }, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid account id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/transfer": { "post": { "summary": "Fund Transfer", "description": "Transfers funds from one account, wallet, or card to another.", "operationId": "fund-transfer", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["debitAccountId", "amount"], "properties": { "debitAccountId": { "type": "string", "description": "The `_id` of the account/wallet to debit the funds from." }, "creditAccountId": { "type": "string", "description": "The `_id` of the account/wallet to receive the funds." }, "amount": { "type": "number", "description": "The amount to be transfered.", "format": "float" }, "narration": { "type": "string", "description": "The narration of the transfer." }, "paymentReference": { "type": "string", "description": "A payment reference can be provided to be attached to the transfer." } } } } } }, "responses": { "200": { "description": "Transfer completed successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "responseCode": { "type": "string", "description": "Provider response code for the transfer. `00` indicates the transfer was approved or completed successfully." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the transfer record." }, "business": { "type": "string", "description": "Identifier of the business that owns this transfer." }, "account": { "type": "string", "description": "Identifier of the account/wallet the funds were debited from." }, "paymentReference": { "type": "string", "description": "Unique payment reference attached to the transfer." }, "currency": { "type": "string", "description": "Currency the transfer was made in." }, "type": { "type": "string", "description": "Direction of the transfer, e.g. `Outwards`." }, "provider": { "type": "string", "description": "Provider that processed the transfer." }, "providerChannel": { "type": "string", "description": "Channel the provider used to process the transfer, e.g. `Internal`." }, "amount": { "type": "number", "description": "Amount transferred." }, "fees": { "type": "number", "description": "Total fees charged on the transfer." }, "vat": { "type": "number", "description": "VAT charged on the transfer fees." }, "stampDuty": { "type": "number", "description": "Stamp duty charged on the transfer." }, "exchangeRate": { "type": "number", "description": "Exchange rate applied to the transfer." }, "narration": { "type": "string", "description": "Narration / description of the transfer." }, "destination": { "type": "object", "description": "Details of the account credited by this transfer.", "properties": { "currency": { "type": "string", "description": "Currency of the destination account." }, "amount": { "type": "string", "description": "Amount credited to the destination account." }, "accountName": { "type": "string", "description": "Name on the destination account." }, "bankCode": { "type": "string", "description": "Bank code of the destination account." }, "accountType": { "type": "string", "description": "Type of the destination account, e.g. `Current`." }, "accountNumber": { "type": "string", "description": "Account number / identifier of the destination account." } } }, "status": { "type": "string", "description": "Current status of the transfer, e.g. `completed`." }, "responseCode": { "type": "string", "description": "Provider response code. `00` indicates success." }, "responseMessage": { "type": "string", "description": "Human-readable provider response message." }, "isReversed": { "type": "boolean", "description": "Whether the transfer has been reversed." }, "isDeleted": { "type": "boolean", "description": "Whether the transfer record has been deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp the transfer was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp the transfer was last updated." }, "__v": { "type": "integer", "description": "Document version key." } } } } }, "example": { "statusCode": 200, "responseCode": "00", "message": "Approved or completed successfully", "data": { "_id": "6a66fe4cd74ec1b35b2e9f11", "business": "696edb9889c90df3bcdbe067", "account": "6a0c36fca2fad1bab0723521", "paymentReference": "SudoHUSMC-6ff94679d2469", "currency": "USD", "type": "Outwards", "provider": "Sudo", "providerChannel": "Internal", "amount": 123, "fees": 0, "vat": 0, "stampDuty": 0, "exchangeRate": 1, "narration": "Sudo MasterCard Funding|SudoHUSMC-6ff94679d2469", "destination": { "currency": "USD", "amount": "123.00", "accountName": "Prince Muteh", "bankCode": "SudoHUSMC", "accountType": "Current", "accountNumber": "b9803bdc-5f40-47e2-b3f9-a447a4260cfe" }, "status": "completed", "responseCode": "00", "responseMessage": "Approved or completed successfully", "isReversed": false, "isDeleted": false, "createdAt": "2026-07-27T06:44:28.233Z", "updatedAt": "2026-07-27T06:44:28.233Z", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Insufficient funds.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/card-programs": { "parameters": [], "post": { "summary": "Create Card Program", "responses": { "201": { "description": "200", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "Description text." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." }, "status": { "type": "string", "description": "Current status of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "debitAccount": { "type": "string", "description": "Identifier of the account debited for this program." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "design": { "nullable": true, "description": "Card design reference, or `null` for the default design." }, "cardBrand": { "type": "string", "description": "Card scheme/brand for the program." }, "cardType": { "type": "string", "description": "Card form factor for the program (`physical` or `virtual`)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} } } } } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "nullable": true, "description": "ISO 8601 timestamp of when the object was last updated." }, "deletedAt": { "nullable": true, "description": "ISO 8601 timestamp of when the object was deleted, if applicable." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Card program created successfully.", "data": { "name": "Physical Verve Prepaid Cards", "description": "For Physical Verve Prepaid Cards", "reference": "250604-2156", "status": "active", "business": "670cec9d25852ba485d74273", "debitAccount": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "currency": "NGN", "design": null, "cardBrand": "Verve", "cardType": "physical", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [] } ] }, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": null, "deletedAt": null, "_id": "6840b5161443c90831ba07a5", "__v": 0 } } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "debitAccountId": { "type": "string" }, "fundingSourceId": { "type": "string" }, "issuerCountry": { "type": "string" }, "currency": { "type": "string" }, "cardBrand": { "type": "string" }, "cardType": { "type": "string" } } }, "example": { "name": "Virtual Verve Debit Cards", "description": "For Virtual Verve Debit Cards", "status": "active", "debitAccountId": "67974b365c184d20fc340889", "fundingSourceId": "670cece725852ba485d745c7", "issuerCountry": "NGA", "currency": "NGN", "cardBrand": "Verve", "cardType": "virtual", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [] } ] } } } } } }, "get": { "summary": "Get Card Programs", "parameters": [ { "name": "searchTerm", "in": "query", "required": false, "example": "Verve", "schema": { "type": "string" } }, { "name": "cardType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cardBrand", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "example": "NGN", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "fromDate", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "toDate", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card programs fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "Description text." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." }, "status": { "type": "string", "description": "Current status of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "debitAccount": { "type": "string", "description": "Identifier of the account debited for this program." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "design": { "nullable": true, "description": "Card design reference, or `null` for the default design." }, "cardBrand": { "type": "string", "description": "Card scheme/brand for the program." }, "cardType": { "type": "string", "description": "Card form factor for the program (`physical` or `virtual`)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} } } } } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "nullable": true, "description": "ISO 8601 timestamp of when the object was last updated." }, "deletedAt": { "nullable": true, "description": "ISO 8601 timestamp of when the object was deleted, if applicable." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Card programs fetched successfully.", "data": [ { "name": "Physical Verve Prepaid Cards", "description": "For Physical Verve Prepaid Cards", "reference": "250604-2156", "status": "active", "business": "670cec9d25852ba485d74273", "debitAccount": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "currency": "NGN", "design": null, "cardBrand": "Verve", "cardType": "physical", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [] } ] }, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": null, "deletedAt": null, "_id": "6840b5161443c90831ba07a5", "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid pagination parameters.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } } } }, "/card-programs/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "example": "6840b5161443c90831ba07a5", "schema": { "type": "integer" } } ], "get": { "summary": "Get a Card Program", "responses": { "200": { "description": "Card program fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "Description text." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." }, "status": { "type": "string", "description": "Current status of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "debitAccount": { "type": "string", "description": "Identifier of the account debited for this program." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "design": { "nullable": true, "description": "Card design reference, or `null` for the default design." }, "cardBrand": { "type": "string", "description": "Card scheme/brand for the program." }, "cardType": { "type": "string", "description": "Card form factor for the program (`physical` or `virtual`)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} } } } } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "nullable": true, "description": "ISO 8601 timestamp of when the object was last updated." }, "deletedAt": { "nullable": true, "description": "ISO 8601 timestamp of when the object was deleted, if applicable." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Card program fetched successfully.", "data": { "name": "Physical Verve Prepaid Cards", "description": "For Physical Verve Prepaid Cards", "reference": "250604-2156", "status": "active", "business": "670cec9d25852ba485d74273", "debitAccount": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "currency": "NGN", "design": null, "cardBrand": "Verve", "cardType": "physical", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [] } ] }, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": null, "deletedAt": null, "_id": "6840b5161443c90831ba07a5", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card program id.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Card program not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } } }, "patch": { "summary": "Update a Card Program", "responses": { "201": { "description": "200", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "name": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "Description text." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." }, "status": { "type": "string", "description": "Current status of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "debitAccount": { "type": "string", "description": "Identifier of the account debited for this program." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "design": { "nullable": true, "description": "Card design reference, or `null` for the default design." }, "cardBrand": { "type": "string", "description": "Card scheme/brand for the program." }, "cardType": { "type": "string", "description": "Card form factor for the program (`physical` or `virtual`)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} } } } } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "nullable": true, "description": "ISO 8601 timestamp of when the object was last updated." }, "deletedAt": { "nullable": true, "description": "ISO 8601 timestamp of when the object was deleted, if applicable." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Card program created successfully.", "data": { "name": "Physical Verve Prepaid Cards", "description": "For Physical Verve Prepaid Cards", "reference": "250604-2156", "status": "active", "business": "670cec9d25852ba485d74273", "debitAccount": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "currency": "NGN", "design": null, "cardBrand": "Verve", "cardType": "physical", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [] } ] }, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": null, "deletedAt": null, "_id": "6840b5161443c90831ba07a5", "__v": 0 } } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "debitAccountId": { "type": "string" }, "fundingSourceId": { "type": "string" }, "issuerCountry": { "type": "string" }, "currency": { "type": "string" }, "cardBrand": { "type": "string" }, "cardType": { "type": "string" } } }, "example": { "name": "Virtual Verve Debit Cards", "description": "For Virtual Verve Debit Cards", "status": "active", "debitAccountId": "67974b365c184d20fc340889", "fundingSourceId": "670cece725852ba485d745c7", "issuerCountry": "NGA", "currency": "NGN", "cardBrand": "Verve", "cardType": "virtual" } } } } } }, "/card-programs/{id}/cards": { "parameters": [ { "name": "id", "in": "path", "required": true, "example": "6840b5161443c90831ba07a5", "schema": { "type": "integer" } } ], "get": { "summary": "Get Cards By a Program", "responses": { "200": { "description": "Cards fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": { "createdBy": { "type": "string", "description": "Identifier of the actor that created the object." }, "purpose": { "type": "string", "description": "Free-text purpose of the card." } } }, "status": { "type": "string", "description": "Current status of the object." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} }, "_id": { "type": "string", "description": "Unique identifier of the object." } } } }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Cards fetched successfully.", "data": [ { "business": "670cec9d25852ba485d74273", "customer": "64a1b2c3d4e5f6a7b8c9d0e1", "account": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506110******1234", "expiryMonth": "09", "expiryYear": "2028", "metadata": { "createdBy": "api", "purpose": "general" }, "status": "active", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true, "_id": "6840b5161443c90831ba07b1" }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [], "_id": "6840b5161443c90831ba07b2" } ], "_id": "6840b5161443c90831ba07b0" }, "is2FAEnrolled": false, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "_id": "6418eb71a37e405064694518", "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card program id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } } } }, "/cards": { "post": { "summary": "Create Card", "description": "Create, map or replace cards for a specific customer.", "operationId": "create-card", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "type", "currency", "status"], "properties": { "customerId": { "type": "string", "description": "The customer `_id`." }, "fundingSourceId": { "type": "string", "description": "The funding source `_id`. Required if you wish to map card to an existing funding source." }, "type": { "type": "string", "description": "The card type.", "default": "physical", "enum": ["physical", "virtual"] }, "brand": { "type": "string", "description": "The card brand.", "enum": ["Verve", "AfriGo", "MasterCard", "Visa"] }, "number": { "type": "string", "description": "The card PAN (Verve or AfriGo) or Card ID (Visa). Required if `type` is `physical`." }, "enable2FA": { "type": "boolean", "description": "Enable 2FA for the card, this enables the card to receive OTP for web and mobile transactions.", "default": false }, "currency": { "type": "string", "description": "The currency type.", "default": "NGN", "enum": ["NGN", "USD"] }, "issuerCountry": { "type": "string", "description": "3 Digits Issuer Country. `NGA` for Nigeria and `USA` for United States. Defaults to `NGA`.", "default": "NGA", "enum": ["NGA", "USA"] }, "status": { "type": "string", "description": "The initial card status.", "default": "active", "enum": ["active", "inactive"] }, "metadata": { "type": "string", "description": "The metadata object to attach to the card. Stored in key-value pair", "format": "json" }, "spendingControls": { "type": "object", "description": "Card spending controls. Default usage limits will be applied if non is provided.", "properties": { "allowedCategories": { "type": "array", "description": "Array of allowed categories (MCC).", "default": [], "items": { "type": "string" } }, "blockedCategories": { "type": "array", "description": "Array of blocked categories (MCC).", "default": [], "items": { "type": "string" } }, "channels": { "type": "object", "description": "Channels allowed to use card on", "properties": { "atm": { "type": "boolean", "description": "Set to `true` to allow atm transactions. Otherwise, set to `false`.", "default": true }, "pos": { "type": "boolean", "description": "Set to `true` to allow pos transactions. Otherwise, set to `false`.", "default": true }, "web": { "type": "boolean", "description": "Set to `true` to allow web transactions. Otherwise, set to `false`.", "default": true }, "mobile": { "type": "boolean", "description": "Set to `true` to allow mobile transactions.", "default": true } } }, "spendingLimits": { "type": "array", "description": "Array of spending limit objects.", "items": { "properties": { "amount": { "type": "integer", "description": "The amount to set as limit.", "format": "int32" }, "interval": { "type": "string", "description": "The limit interval.", "default": "daily", "enum": ["daily", "weekly", "monthly", "yearly"] } }, "required": ["amount", "interval"], "type": "object" } } } }, "bankCode": { "type": "string", "description": "The bank code of existing account. Required if you wish to map card to existing account." }, "accountNumber": { "type": "string", "description": "The account number of existing account. Required if you wish to map card to existing account." }, "replacementFor": { "type": "string", "description": "The `_id` of the current card you wish to replace. Required for card replacement." }, "replacementReason": { "type": "string", "description": "The reason for replacement. Required for card replacement.", "enum": ["lost", "stolen"] }, "debitAccountId": { "type": "string", "description": "Debit account `_id`. Required for all virtual cards and giftcards." }, "amount": { "type": "integer", "description": "Funding amount. Required for mastercard.", "format": "int32" }, "sendPINSMS": { "type": "boolean", "description": "Send default PIN to customer phone number via SMS.", "default": false }, "expirationDate": { "type": "string", "description": "Card expiry date. Applies to Visa cards only. Format `MMM-YYYY` example `AUG-2025`. All cards are subject to maximum of 3 years validity." } } } } } }, "responses": { "201": { "description": "Card created successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": { "createdBy": { "type": "string", "description": "Identifier of the actor that created the object." }, "purpose": { "type": "string", "description": "Free-text purpose of the card." } } }, "status": { "type": "string", "description": "Current status of the object." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} }, "_id": { "type": "string", "description": "Unique identifier of the object." } } } }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Card created successfully.", "data": { "business": "670cec9d25852ba485d74273", "customer": "64a1b2c3d4e5f6a7b8c9d0e1", "account": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506110******1234", "expiryMonth": "09", "expiryYear": "2028", "metadata": { "createdBy": "api", "purpose": "general" }, "status": "active", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true, "_id": "6840b5161443c90831ba07b1" }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [], "_id": "6840b5161443c90831ba07b2" } ], "_id": "6840b5161443c90831ba07b0" }, "is2FAEnrolled": false, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "_id": "6418eb71a37e405064694518", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"customerId\" is required", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "get": { "summary": "Get Cards", "description": "Fetches cards according to query parameters.", "operationId": "get-cards", "parameters": [{ "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of cards to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }], "responses": { "200": { "description": "Cards fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": { "createdBy": { "type": "string", "description": "Identifier of the actor that created the object." }, "purpose": { "type": "string", "description": "Free-text purpose of the card." } } }, "status": { "type": "string", "description": "Current status of the object." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} }, "_id": { "type": "string", "description": "Unique identifier of the object." } } } }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Cards fetched successfully.", "data": [ { "business": "670cec9d25852ba485d74273", "customer": "64a1b2c3d4e5f6a7b8c9d0e1", "account": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506110******1234", "expiryMonth": "09", "expiryYear": "2028", "metadata": { "createdBy": "api", "purpose": "general" }, "status": "active", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true, "_id": "6840b5161443c90831ba07b1" }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [], "_id": "6840b5161443c90831ba07b2" } ], "_id": "6840b5161443c90831ba07b0" }, "is2FAEnrolled": false, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "_id": "6418eb71a37e405064694518", "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid pagination parameters.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/customer/{id}": { "get": { "summary": "Get Customer Cards", "description": "Fetches all cards that are mapped to a specific customer according to the query parameters.", "operationId": "get-customer-cards", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the customer you wish to fetch the cards for.", "schema": { "type": "string" }, "required": true }, { "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of mapped cards to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }], "responses": { "200": { "description": "Customer cards fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": { "createdBy": { "type": "string", "description": "Identifier of the actor that created the object." }, "purpose": { "type": "string", "description": "Free-text purpose of the card." } } }, "status": { "type": "string", "description": "Current status of the object." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} }, "_id": { "type": "string", "description": "Unique identifier of the object." } } } }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Customer cards fetched successfully.", "data": [ { "business": "670cec9d25852ba485d74273", "customer": "64a1b2c3d4e5f6a7b8c9d0e1", "account": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506110******1234", "expiryMonth": "09", "expiryYear": "2028", "metadata": { "createdBy": "api", "purpose": "general" }, "status": "active", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true, "_id": "6840b5161443c90831ba07b1" }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [], "_id": "6840b5161443c90831ba07b2" } ], "_id": "6840b5161443c90831ba07b0" }, "is2FAEnrolled": false, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "_id": "6418eb71a37e405064694518", "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid customer id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/{id}": { "get": { "summary": "Get Card", "description": "Fetches the details of a specific card.", "operationId": "get-card", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the card to fetch.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Card fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": { "createdBy": { "type": "string", "description": "Identifier of the actor that created the object." }, "purpose": { "type": "string", "description": "Free-text purpose of the card." } } }, "status": { "type": "string", "description": "Current status of the object." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} }, "_id": { "type": "string", "description": "Unique identifier of the object." } } } }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Card fetched successfully.", "data": { "business": "670cec9d25852ba485d74273", "customer": "64a1b2c3d4e5f6a7b8c9d0e1", "account": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506110******1234", "expiryMonth": "09", "expiryYear": "2028", "metadata": { "createdBy": "api", "purpose": "general" }, "status": "active", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true, "_id": "6840b5161443c90831ba07b1" }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [], "_id": "6840b5161443c90831ba07b2" } ], "_id": "6840b5161443c90831ba07b0" }, "is2FAEnrolled": false, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "_id": "6418eb71a37e405064694518", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Card not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "put": { "summary": "Update Card", "description": "Update details for a specific card.", "operationId": "update-card", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the card to update.", "schema": { "type": "string" }, "required": true }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "fundingSourceId": { "type": "string", "description": "The funding source `_id`. Required if you wish to map card to an existing funding source." }, "status": { "type": "string", "description": "The card status.", "default": "active", "enum": ["active", "inactive", "canceled"] }, "metadata": { "type": "string", "description": "The metadata object to attach to the card. Stored in key-value pair", "format": "json" }, "spendingControls": { "type": "object", "description": "Card spending controls. Default usage limits will be applied if non is provided.", "properties": { "allowedCategories": { "type": "array", "description": "Array of allowed categories (MCC).", "default": [], "items": { "type": "string" } }, "blockedCategories": { "type": "array", "description": "Array of blocked categories (MCC).", "default": [], "items": { "type": "string" } }, "channels": { "type": "object", "description": "Channels allowed to use card on", "properties": { "atm": { "type": "boolean", "description": "Set to `true` to allow atm transactions. Otherwise, set to `false`.", "default": true }, "pos": { "type": "boolean", "description": "Set to `true` to allow pos transactions. Otherwise, set to `false`.", "default": true }, "web": { "type": "boolean", "description": "Set to `true` to allow web transactions. Otherwise, set to `false`.", "default": true }, "mobile": { "type": "boolean", "description": "Set to `true` to allow mobile transactions.", "default": true } } }, "spendingLimits": { "type": "array", "description": "Array of spending limit objects.", "items": { "properties": { "amount": { "type": "integer", "description": "The amount to set as limit.", "format": "int32" }, "interval": { "type": "string", "description": "The limit interval.", "default": "daily", "enum": ["daily", "weekly", "monthly", "yearly"] } }, "required": ["amount", "interval"], "type": "object" } } } }, "cancellationReason": { "type": "string", "description": "Required if status is set to `canceled`", "enum": ["lost", "stolen"] }, "creditAccountId": { "type": "string", "description": "The credit account `_id`. Required for `canceled` status only." } } } } } }, "responses": { "200": { "description": "Card updated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": { "createdBy": { "type": "string", "description": "Identifier of the actor that created the object." }, "purpose": { "type": "string", "description": "Free-text purpose of the card." } } }, "status": { "type": "string", "description": "Current status of the object." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "interval": { "type": "string", "description": "Interval the limit applies over (`daily`, `weekly`, `monthly`, `yearly`)." }, "categories": { "type": "array", "description": "Merchant category codes the limit applies to.", "items": {} }, "_id": { "type": "string", "description": "Unique identifier of the object." } } } }, "_id": { "type": "string", "description": "Unique identifier of the object." } } }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Card updated successfully.", "data": { "business": "670cec9d25852ba485d74273", "customer": "64a1b2c3d4e5f6a7b8c9d0e1", "account": "67974b365c184d20fc340889", "fundingSource": "670cec9d25852ba485d74286", "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506110******1234", "expiryMonth": "09", "expiryYear": "2028", "metadata": { "createdBy": "api", "purpose": "general" }, "status": "inactive", "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true, "_id": "6840b5161443c90831ba07b1" }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [ { "amount": 1500000, "interval": "daily", "categories": [], "_id": "6840b5161443c90831ba07b2" } ], "_id": "6840b5161443c90831ba07b0" }, "is2FAEnrolled": false, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "isDeleted": false, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "_id": "6418eb71a37e405064694518", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"status\" must be one of [active, inactive, canceled]", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Card not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/{id}/balance": { "get": { "summary": "Get Card Balance", "description": "Fetches the balance of the specified card.", "operationId": "get-card-balance", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the card you wish to fetch the balance for.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Card balance fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." } } } } }, "example": { "statusCode": 200, "message": "Card balance fetched successfully.", "data": { "currentBalance": 18000, "availableBalance": 18000 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/digitalize/{id}": { "put": { "summary": "Digitalize Card", "description": "Fetches required payload for Card Digitalization SDK for a specific card.", "operationId": "digitalize-card", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the card to fetch.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Card digitalization initiated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "status": { "type": "string", "description": "Current status of the object." }, "card": { "type": "string", "description": "Associated card \u2014 an id, or a summary object on nested resources." } } } } }, "example": { "statusCode": 200, "message": "Card digitalization initiated successfully.", "data": { "status": "pending", "card": "6418eb71a37e405064694518" } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/simulator/fund": { "post": { "summary": "Fund Account", "description": "Funds an account with the specified amount.", "operationId": "fund-account", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["amount"], "properties": { "accountId": { "type": "string", "description": "The `_id` of the account you wish to fund. Required if you wish to fund account using the id." }, "amount": { "type": "number", "description": "The amount to add to account.", "default": 100, "format": "float" }, "bankCode": { "type": "string", "description": "The bank code of the specified account. Required if you wish to fund account using the account number." }, "accountNumber": { "type": "string", "description": "The number of the specified account. Required if you wish to fund account using the account number." } } } } } }, "responses": { "200": { "description": "Account funded successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "responseCode": { "type": "string", "description": "Transfer response code (`00` indicates success)." } } }, "example": { "statusCode": 200, "message": "Approved or completed successfully", "responseCode": "00" } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid account id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/simulator/generate": { "get": { "summary": "Generate Test Card", "description": "Generates a test card which can be mapped to a customer or used to simulate authorisations or balance enquiry.", "operationId": "generate-test-card", "responses": { "200": { "description": "Card generated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "number": { "type": "string", "description": "Identity / card number value." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "integer", "description": "Card expiry year (YYYY)." }, "cvv2": { "type": "string", "description": "Card verification value (sandbox/test only)." } } } } }, "example": { "statusCode": 200, "message": "Card generated successfully.", "data": { "number": "506321001162831776", "expiryMonth": "06", "expiryYear": 2029, "cvv2": "tok_dev_fbsATqyRayEnqawvgMUAw2" } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Could not generate test card.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/simulator/balance_enqiry": { "post": { "summary": "Balance Enquiry", "description": "Simulates card enquiry for a specific card.", "operationId": "balance-enquiry", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["cardId", "channel"], "properties": { "cardId": { "type": "string", "description": "The `_id` of the specific card." }, "channel": { "type": "string", "description": "The channel to simulate the balance enquiry on.", "default": "web", "enum": ["web", "pos", "atm"] } } } } } }, "responses": { "200": { "description": "Simulated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." } } }, "example": { "statusCode": 200, "message": "Simulated successfully." } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/simulator/authorization": { "post": { "summary": "Simulate Authorization", "description": "Simulates different types of authorizations across several merchant categories and channels.", "operationId": "simulate-authorization", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["cardId", "channel", "type", "amount", "currency", "merchant"], "properties": { "cardId": { "type": "string", "description": "The `_id` of the card." }, "channel": { "type": "string", "description": "The channel to simulate the authorization on.", "default": "web", "enum": ["web", "pos", "atm"] }, "type": { "type": "string", "description": "The authorization type.", "default": "purchase", "enum": ["purchase", "cash_withdrawal", "deposit", "transfer", "payment"] }, "amount": { "type": "number", "description": "The amount to simulate.", "format": "float" }, "currency": { "type": "string", "description": "The currency type.", "default": "NGN", "enum": ["NGN", "USD"] }, "merchant": { "type": "object", "description": "The merchant information.", "required": ["category", "merchantId", "name", "city", "state", "country"], "properties": { "category": { "type": "string", "description": "The merchant category" }, "merchantId": { "type": "string", "description": "The `_id` of the merchant." }, "name": { "type": "string", "description": "The merchant name." }, "city": { "type": "string", "description": "The city the merchant is located." }, "state": { "type": "string", "description": "The two letter code of the state the merchant is located in." }, "country": { "type": "string", "description": "The two letter code of the country the merchant is located in." } } } } } } } }, "responses": { "200": { "description": "Simulated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." } } }, "example": { "statusCode": 200, "message": "Simulated successfully." } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/simulator/authorization/{id}/reversal": { "get": { "summary": "Simulate Authorization Reversal", "description": "Simulates different types of authorizations across several merchant categories and channels.", "operationId": "simulate-authorization-reversal", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the authorization you wish to reverse.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Authorization reversed successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "name": { "type": "string", "description": "Display name." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." } } }, "pendingRequest": { "type": "object", "description": "Details of the amount currently being authorized.", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "integer", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Authorization reversed successfully.", "data": { "_id": "6840c1aa2b3c4d5e6f700222", "business": "670cec9d25852ba485d74273", "customer": { "_id": "64a1b2c3d4e5f6a7b8c9d0e1", "name": "John Doe" }, "account": { "_id": "67974b365c184d20fc340889", "type": "account", "currency": "NGN", "accountName": "John Doe", "accountNumber": "1234567890" }, "card": { "_id": "6418eb71a37e405064694518", "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506110******1234" }, "pendingRequest": { "amount": 5000, "currency": "NGN", "merchantAmount": 5000, "merchantCurrency": "NGN" }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "TRX-250604-2156" }, "amount": 5000, "fee": 0, "vat": 0, "approved": true, "currency": "NGN", "status": "reversed", "authorizationMethod": "online", "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid authorization id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/authorizations": { "get": { "summary": "Get Authorizations", "description": "Fetches all authorizations for all cards according to the query parameters.", "operationId": "get-authorizations", "parameters": [{ "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of authorizations to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "fromDate", "in": "query", "description": "This is the start date of the date range.", "schema": { "type": "string", "format": "date" } }, { "name": "toDate", "in": "query", "description": "This is the end date of the date range.", "schema": { "type": "string", "format": "date" } }], "responses": { "200": { "description": "Authorizations fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "status": { "type": "string", "description": "Current status of the object." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "format": "date-time", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "failedTransactionCount": { "type": "integer" }, "minimumBalance": { "type": "integer" }, "version": { "type": "string" }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "program": { "nullable": true }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "status": { "type": "string", "description": "Current status of the object." }, "is2FAEnabled": { "type": "boolean" }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "providerReference": { "type": "string" }, "isDigitalized": { "type": "boolean" }, "accumulatedFees": { "type": "integer" }, "totalFeesCharged": { "type": "integer" }, "feeChargeDay": { "type": "integer" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": {} } } } } }, "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "number", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "pendingRequest": { "nullable": true, "description": "Details of the amount currently being authorized." }, "requestHistory": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." } } } }, "verification": { "type": "object", "properties": { "billingAddressLine1": { "type": "string" }, "billingAddressPostalCode": { "type": "string" }, "cvv": { "type": "string" }, "expiry": { "type": "string" }, "pin": { "type": "string" }, "threeDSecure": { "type": "string" }, "safeToken": { "type": "string" }, "authentication": { "type": "string" } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Authorizations fetched successfully.", "data": [ { "_id": "6a43ba89134c39198fe21652", "business": "696edb9889c90df3bcdbe067", "customer": { "_id": "69ba46bb734a4457f2d063f5", "business": "696edb9889c90df3bcdbe067", "type": "individual", "name": "Prince Muteh", "phoneNumber": "7030338024", "emailAddress": "prince.muteh@gmail.com", "status": "active", "individual": { "firstName": "Prince", "lastName": "Muteh", "otherNames": "", "dob": "2026-03-18T00:00:00.000Z", "identity": { "type": "BVN", "number": "1234567890" } }, "billingAddress": { "line1": "University Of Maiduguri", "line2": "", "city": "Garki", "state": "Abuja Federal Capital Territory", "country": "Nigeria", "postalCode": "600211" }, "isDeleted": false, "createdAt": "2026-03-18T06:31:23.112Z", "updatedAt": "2026-03-18T06:31:23.112Z", "__v": 0 }, "account": { "_id": "69ba46d6734a4457f2d06428", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRINCE MUTEH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010251947", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "69ba46d6012c2100246f7a38", "referenceCode": "subacc_1773815509991", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-03-18T06:31:50.409Z", "updatedAt": "2026-03-18T06:31:50.409Z", "charges": [], "__v": 0 }, "card": { "failedTransactionCount": 0, "minimumBalance": 0, "version": "v1", "_id": "69ba46d8734a4457f2d06430", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "fundingSource": "69ba4677734a4457f2d06383", "program": null, "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506321*********3111", "expiryMonth": "03", "expiryYear": "2029", "status": "active", "is2FAEnabled": true, "is2FAEnrolled": true, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "providerReference": "69ba46d8a61d0550d690e79e", "isDigitalized": false, "accumulatedFees": 0, "totalFeesCharged": 0, "feeChargeDay": 1, "isDeleted": false, "createdAt": "2026-03-18T06:31:52.457Z", "updatedAt": "2026-06-30T12:55:52.640Z", "__v": 0, "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [] } }, "amount": 10005.38, "fee": 5, "vat": 0.38, "approved": true, "currency": "NGN", "status": "approved", "authorizationMethod": "online", "balanceTransactions": [], "merchantAmount": 10000, "merchantCurrency": "NGN", "merchant": { "category": "0742", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "149283196621", "stan": "148345", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947149283196621" }, "pendingRequest": null, "requestHistory": [ { "amount": 10005.38, "currency": "NGN", "approved": true, "merchantAmount": 10000, "merchantCurrency": "NGN", "reason": "webhook_approved", "createdAt": "2026-06-30T12:46:01.932Z" } ], "verification": { "billingAddressLine1": "not_provided", "billingAddressPostalCode": "not_provided", "cvv": "match", "expiry": "match", "pin": "match", "threeDSecure": "not_provided", "safeToken": "match", "authentication": "pin" }, "isDeleted": false, "createdAt": "2026-06-30T12:46:01.932Z", "updatedAt": "2026-06-30T12:46:01.932Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" } ], "__v": 1 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid pagination parameters.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/{id}/authorizations": { "get": { "summary": "Get Card Authorizations", "description": "Fetches all authorizations for a specific card according to the query parameters.", "operationId": "get-card-authorizations", "parameters": [{ "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of authorizations to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "fromDate", "in": "query", "description": "This is the start date of the date range.", "schema": { "type": "string", "format": "date" } }, { "name": "toDate", "in": "query", "description": "This is the end date of the date range.", "schema": { "type": "string", "format": "date" } }, { "name": "id", "in": "path", "description": "The `_id` of the card you wish to fetch the authorizations for.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Authorizations fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "status": { "type": "string", "description": "Current status of the object." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "format": "date-time", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "failedTransactionCount": { "type": "integer" }, "minimumBalance": { "type": "integer" }, "version": { "type": "string" }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "program": { "nullable": true }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "status": { "type": "string", "description": "Current status of the object." }, "is2FAEnabled": { "type": "boolean" }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "providerReference": { "type": "string" }, "isDigitalized": { "type": "boolean" }, "accumulatedFees": { "type": "integer" }, "totalFeesCharged": { "type": "integer" }, "feeChargeDay": { "type": "integer" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": {} } } } } }, "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "number", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "pendingRequest": { "nullable": true, "description": "Details of the amount currently being authorized." }, "requestHistory": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." } } } }, "verification": { "type": "object", "properties": { "billingAddressLine1": { "type": "string" }, "billingAddressPostalCode": { "type": "string" }, "cvv": { "type": "string" }, "expiry": { "type": "string" }, "pin": { "type": "string" }, "threeDSecure": { "type": "string" }, "safeToken": { "type": "string" }, "authentication": { "type": "string" } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Authorizations fetched successfully.", "data": [ { "_id": "6a43ba89134c39198fe21652", "business": "696edb9889c90df3bcdbe067", "customer": { "_id": "69ba46bb734a4457f2d063f5", "business": "696edb9889c90df3bcdbe067", "type": "individual", "name": "Prince Muteh", "phoneNumber": "7030338024", "emailAddress": "prince.muteh@gmail.com", "status": "active", "individual": { "firstName": "Prince", "lastName": "Muteh", "otherNames": "", "dob": "2026-03-18T00:00:00.000Z", "identity": { "type": "BVN", "number": "1234567890" } }, "billingAddress": { "line1": "University Of Maiduguri", "line2": "", "city": "Garki", "state": "Abuja Federal Capital Territory", "country": "Nigeria", "postalCode": "600211" }, "isDeleted": false, "createdAt": "2026-03-18T06:31:23.112Z", "updatedAt": "2026-03-18T06:31:23.112Z", "__v": 0 }, "account": { "_id": "69ba46d6734a4457f2d06428", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRINCE MUTEH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010251947", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "69ba46d6012c2100246f7a38", "referenceCode": "subacc_1773815509991", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-03-18T06:31:50.409Z", "updatedAt": "2026-03-18T06:31:50.409Z", "charges": [], "__v": 0 }, "card": { "failedTransactionCount": 0, "minimumBalance": 0, "version": "v1", "_id": "69ba46d8734a4457f2d06430", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "fundingSource": "69ba4677734a4457f2d06383", "program": null, "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506321*********3111", "expiryMonth": "03", "expiryYear": "2029", "status": "active", "is2FAEnabled": true, "is2FAEnrolled": true, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "providerReference": "69ba46d8a61d0550d690e79e", "isDigitalized": false, "accumulatedFees": 0, "totalFeesCharged": 0, "feeChargeDay": 1, "isDeleted": false, "createdAt": "2026-03-18T06:31:52.457Z", "updatedAt": "2026-06-30T12:55:52.640Z", "__v": 0, "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [] } }, "amount": 10005.38, "fee": 5, "vat": 0.38, "approved": true, "currency": "NGN", "status": "approved", "authorizationMethod": "online", "balanceTransactions": [], "merchantAmount": 10000, "merchantCurrency": "NGN", "merchant": { "category": "0742", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "149283196621", "stan": "148345", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947149283196621" }, "pendingRequest": null, "requestHistory": [ { "amount": 10005.38, "currency": "NGN", "approved": true, "merchantAmount": 10000, "merchantCurrency": "NGN", "reason": "webhook_approved", "createdAt": "2026-06-30T12:46:01.932Z" } ], "verification": { "billingAddressLine1": "not_provided", "billingAddressPostalCode": "not_provided", "cvv": "match", "expiry": "match", "pin": "match", "threeDSecure": "not_provided", "safeToken": "match", "authentication": "pin" }, "isDeleted": false, "createdAt": "2026-06-30T12:46:01.932Z", "updatedAt": "2026-06-30T12:46:01.932Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" } ], "__v": 1 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/authorizations/{id}": { "get": { "summary": "Get Authorization", "description": "Fetches details about a specific authorization using the provided id.", "operationId": "get-authorization", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the authorization to fetch.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Authorization fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "status": { "type": "string", "description": "Current status of the object." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "format": "date-time", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "failedTransactionCount": { "type": "integer" }, "minimumBalance": { "type": "integer" }, "version": { "type": "string" }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "program": { "nullable": true }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "status": { "type": "string", "description": "Current status of the object." }, "is2FAEnabled": { "type": "boolean" }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "providerReference": { "type": "string" }, "isDigitalized": { "type": "boolean" }, "accumulatedFees": { "type": "integer" }, "totalFeesCharged": { "type": "integer" }, "feeChargeDay": { "type": "integer" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": {} } } } } }, "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "number", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "pendingRequest": { "nullable": true, "description": "Details of the amount currently being authorized." }, "requestHistory": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." } } } }, "verification": { "type": "object", "properties": { "billingAddressLine1": { "type": "string" }, "billingAddressPostalCode": { "type": "string" }, "cvv": { "type": "string" }, "expiry": { "type": "string" }, "pin": { "type": "string" }, "threeDSecure": { "type": "string" }, "safeToken": { "type": "string" }, "authentication": { "type": "string" } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Authorization fetched successfully.", "data": { "_id": "6a43ba89134c39198fe21652", "business": "696edb9889c90df3bcdbe067", "customer": { "_id": "69ba46bb734a4457f2d063f5", "business": "696edb9889c90df3bcdbe067", "type": "individual", "name": "Prince Muteh", "phoneNumber": "7030338024", "emailAddress": "prince.muteh@gmail.com", "status": "active", "individual": { "firstName": "Prince", "lastName": "Muteh", "otherNames": "", "dob": "2026-03-18T00:00:00.000Z", "identity": { "type": "BVN", "number": "1234567890" } }, "billingAddress": { "line1": "University Of Maiduguri", "line2": "", "city": "Garki", "state": "Abuja Federal Capital Territory", "country": "Nigeria", "postalCode": "600211" }, "isDeleted": false, "createdAt": "2026-03-18T06:31:23.112Z", "updatedAt": "2026-03-18T06:31:23.112Z", "__v": 0 }, "account": { "_id": "69ba46d6734a4457f2d06428", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRINCE MUTEH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010251947", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "69ba46d6012c2100246f7a38", "referenceCode": "subacc_1773815509991", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-03-18T06:31:50.409Z", "updatedAt": "2026-03-18T06:31:50.409Z", "charges": [], "__v": 0 }, "card": { "failedTransactionCount": 0, "minimumBalance": 0, "version": "v1", "_id": "69ba46d8734a4457f2d06430", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "fundingSource": "69ba4677734a4457f2d06383", "program": null, "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506321*********3111", "expiryMonth": "03", "expiryYear": "2029", "status": "active", "is2FAEnabled": true, "is2FAEnrolled": true, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "providerReference": "69ba46d8a61d0550d690e79e", "isDigitalized": false, "accumulatedFees": 0, "totalFeesCharged": 0, "feeChargeDay": 1, "isDeleted": false, "createdAt": "2026-03-18T06:31:52.457Z", "updatedAt": "2026-06-30T12:55:52.640Z", "__v": 0, "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [] } }, "amount": 10005.38, "fee": 5, "vat": 0.38, "approved": true, "currency": "NGN", "status": "approved", "authorizationMethod": "online", "balanceTransactions": [], "merchantAmount": 10000, "merchantCurrency": "NGN", "merchant": { "category": "0742", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "149283196621", "stan": "148345", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947149283196621" }, "pendingRequest": null, "requestHistory": [ { "amount": 10005.38, "currency": "NGN", "approved": true, "merchantAmount": 10000, "merchantCurrency": "NGN", "reason": "webhook_approved", "createdAt": "2026-06-30T12:46:01.932Z" } ], "verification": { "billingAddressLine1": "not_provided", "billingAddressPostalCode": "not_provided", "cvv": "match", "expiry": "match", "pin": "match", "threeDSecure": "not_provided", "safeToken": "match", "authentication": "pin" }, "isDeleted": false, "createdAt": "2026-06-30T12:46:01.932Z", "updatedAt": "2026-06-30T12:46:01.932Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" } ], "__v": 1 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid authorization id.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Authorization not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "put": { "summary": "Update Authorization", "description": "Fetches details about a specific authorization using the provided id.", "operationId": "update-authorization", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the authorization to fetch.", "schema": { "type": "string" }, "required": true }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "string", "description": "The key-value pair you wish to attach to the authorization object.", "default": "{}", "format": "json" } } } } } }, "responses": { "200": { "description": "Authorization updated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "status": { "type": "string", "description": "Current status of the object." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "format": "date-time", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "failedTransactionCount": { "type": "integer" }, "minimumBalance": { "type": "integer" }, "version": { "type": "string" }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "program": { "nullable": true }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "status": { "type": "string", "description": "Current status of the object." }, "is2FAEnabled": { "type": "boolean" }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "providerReference": { "type": "string" }, "isDigitalized": { "type": "boolean" }, "accumulatedFees": { "type": "integer" }, "totalFeesCharged": { "type": "integer" }, "feeChargeDay": { "type": "integer" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": {} } } } } }, "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "number", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "pendingRequest": { "nullable": true, "description": "Details of the amount currently being authorized." }, "requestHistory": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." } } } }, "verification": { "type": "object", "properties": { "billingAddressLine1": { "type": "string" }, "billingAddressPostalCode": { "type": "string" }, "cvv": { "type": "string" }, "expiry": { "type": "string" }, "pin": { "type": "string" }, "threeDSecure": { "type": "string" }, "safeToken": { "type": "string" }, "authentication": { "type": "string" } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Authorization updated successfully.", "data": { "_id": "6a43ba89134c39198fe21652", "business": "696edb9889c90df3bcdbe067", "customer": { "_id": "69ba46bb734a4457f2d063f5", "business": "696edb9889c90df3bcdbe067", "type": "individual", "name": "Prince Muteh", "phoneNumber": "7030338024", "emailAddress": "prince.muteh@gmail.com", "status": "active", "individual": { "firstName": "Prince", "lastName": "Muteh", "otherNames": "", "dob": "2026-03-18T00:00:00.000Z", "identity": { "type": "BVN", "number": "1234567890" } }, "billingAddress": { "line1": "University Of Maiduguri", "line2": "", "city": "Garki", "state": "Abuja Federal Capital Territory", "country": "Nigeria", "postalCode": "600211" }, "isDeleted": false, "createdAt": "2026-03-18T06:31:23.112Z", "updatedAt": "2026-03-18T06:31:23.112Z", "__v": 0 }, "account": { "_id": "69ba46d6734a4457f2d06428", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRINCE MUTEH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010251947", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "69ba46d6012c2100246f7a38", "referenceCode": "subacc_1773815509991", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-03-18T06:31:50.409Z", "updatedAt": "2026-03-18T06:31:50.409Z", "charges": [], "__v": 0 }, "card": { "failedTransactionCount": 0, "minimumBalance": 0, "version": "v1", "_id": "69ba46d8734a4457f2d06430", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "fundingSource": "69ba4677734a4457f2d06383", "program": null, "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506321*********3111", "expiryMonth": "03", "expiryYear": "2029", "status": "active", "is2FAEnabled": true, "is2FAEnrolled": true, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "providerReference": "69ba46d8a61d0550d690e79e", "isDigitalized": false, "accumulatedFees": 0, "totalFeesCharged": 0, "feeChargeDay": 1, "isDeleted": false, "createdAt": "2026-03-18T06:31:52.457Z", "updatedAt": "2026-06-30T12:55:52.640Z", "__v": 0, "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [] } }, "amount": 10005.38, "fee": 5, "vat": 0.38, "approved": true, "currency": "NGN", "status": "approved", "authorizationMethod": "online", "balanceTransactions": [], "merchantAmount": 10000, "merchantCurrency": "NGN", "merchant": { "category": "0742", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "149283196621", "stan": "148345", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947149283196621" }, "pendingRequest": null, "requestHistory": [ { "amount": 10005.38, "currency": "NGN", "approved": true, "merchantAmount": 10000, "merchantCurrency": "NGN", "reason": "webhook_approved", "createdAt": "2026-06-30T12:46:01.932Z" } ], "verification": { "billingAddressLine1": "not_provided", "billingAddressPostalCode": "not_provided", "cvv": "match", "expiry": "match", "pin": "match", "threeDSecure": "not_provided", "safeToken": "match", "authentication": "pin" }, "isDeleted": false, "createdAt": "2026-06-30T12:46:01.932Z", "updatedAt": "2026-06-30T12:46:01.932Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" } ], "__v": 1 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid metadata.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Authorization not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/transactions": { "get": { "summary": "Get Transactions", "description": "Fetches all transactions for all cards according to the query parameters.", "operationId": "get-transactions", "parameters": [{ "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of transactions to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "fromDate", "in": "query", "description": "This is the start date of the date range.", "schema": { "type": "string", "format": "date" } }, { "name": "toDate", "in": "query", "description": "This is the end date of the date range.", "schema": { "type": "string", "format": "date" } }], "responses": { "200": { "description": "Transactions fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "status": { "type": "string", "description": "Current status of the object." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "format": "date-time", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "failedTransactionCount": { "type": "integer" }, "minimumBalance": { "type": "integer" }, "version": { "type": "string" }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "program": { "nullable": true }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "status": { "type": "string", "description": "Current status of the object." }, "is2FAEnabled": { "type": "boolean" }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "providerReference": { "type": "string" }, "isDigitalized": { "type": "boolean" }, "accumulatedFees": { "type": "integer" }, "totalFeesCharged": { "type": "integer" }, "feeChargeDay": { "type": "integer" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": {} } } } } }, "authorization": { "type": "object", "description": "Identifier of the authorization this transaction belongs to.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "card": { "type": "string", "description": "Associated card \u2014 an id, or a summary object on nested resources." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "integer", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "pendingRequest": { "nullable": true, "description": "Details of the amount currently being authorized." }, "requestHistory": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." } } } }, "verification": { "type": "object", "properties": { "billingAddressLine1": { "type": "string" }, "billingAddressPostalCode": { "type": "string" }, "cvv": { "type": "string" }, "expiry": { "type": "string" }, "pin": { "type": "string" }, "threeDSecure": { "type": "string" }, "safeToken": { "type": "string" }, "authentication": { "type": "string" } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "integer", "description": "VAT charged, in the minor currency unit." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "type": { "type": "string", "description": "Type of the object." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Transactions fetched successfully.", "data": [ { "_id": "69c0087e144d27053ad73f43", "business": "696edb9889c90df3bcdbe067", "customer": { "_id": "69ba46bb734a4457f2d063f5", "business": "696edb9889c90df3bcdbe067", "type": "individual", "name": "Prince Muteh", "phoneNumber": "7030338024", "emailAddress": "prince.muteh@gmail.com", "status": "active", "individual": { "firstName": "Prince", "lastName": "Muteh", "otherNames": "", "dob": "2026-03-18T00:00:00.000Z", "identity": { "type": "BVN", "number": "1234567890" } }, "billingAddress": { "line1": "University Of Maiduguri", "line2": "", "city": "Garki", "state": "Abuja Federal Capital Territory", "country": "Nigeria", "postalCode": "600211" }, "isDeleted": false, "createdAt": "2026-03-18T06:31:23.112Z", "updatedAt": "2026-03-18T06:31:23.112Z", "__v": 0 }, "account": { "_id": "69ba46d6734a4457f2d06428", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRINCE MUTEH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010251947", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "69ba46d6012c2100246f7a38", "referenceCode": "subacc_1773815509991", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-03-18T06:31:50.409Z", "updatedAt": "2026-03-18T06:31:50.409Z", "charges": [], "__v": 0 }, "card": { "failedTransactionCount": 0, "minimumBalance": 0, "version": "v1", "_id": "69ba46d8734a4457f2d06430", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "fundingSource": "69ba4677734a4457f2d06383", "program": null, "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506321*********3111", "expiryMonth": "03", "expiryYear": "2029", "status": "active", "is2FAEnabled": true, "is2FAEnrolled": true, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "providerReference": "69ba46d8a61d0550d690e79e", "isDigitalized": false, "accumulatedFees": 0, "totalFeesCharged": 0, "feeChargeDay": 1, "isDeleted": false, "createdAt": "2026-03-18T06:31:52.457Z", "updatedAt": "2026-06-05T14:10:59.140Z", "__v": 0, "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [] } }, "authorization": { "_id": "69c00879144d27053ad73f33", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "card": "69ba46d8734a4457f2d06430", "amount": 1005, "fee": 5, "vat": 0, "approved": true, "currency": "NGN", "status": "approved", "authorizationMethod": "online", "balanceTransactions": [], "merchantAmount": 1000, "merchantCurrency": "NGN", "merchant": { "category": "0763", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "195930677510", "stan": "124499", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947195930677510" }, "pendingRequest": null, "requestHistory": [ { "amount": 1005, "currency": "NGN", "approved": true, "merchantAmount": 1000, "merchantCurrency": "NGN", "reason": "webhook_approved", "createdAt": "2026-03-22T15:19:21.165Z" } ], "verification": { "billingAddressLine1": "not_provided", "billingAddressPostalCode": "not_provided", "cvv": "match", "expiry": "match", "pin": "match", "threeDSecure": "not_provided", "safeToken": "match", "authentication": "pin" }, "isDeleted": false, "createdAt": "2026-03-22T15:19:21.165Z", "updatedAt": "2026-03-22T15:19:21.165Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" } ], "__v": 1 }, "amount": -1005, "fee": -5, "vat": 0, "currency": "NGN", "type": "capture", "balanceTransactions": [], "merchantAmount": -1000, "merchantCurrency": "NGN", "merchant": { "category": "0763", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "195930677510", "stan": "124499", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947195930677510" }, "isDeleted": false, "createdAt": "2026-03-22T15:19:26.112Z", "updatedAt": "2026-03-22T15:19:26.112Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" }, null ], "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid pagination parameters.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/{id}/transactions": { "get": { "summary": "Get Card Transactions", "description": "Fetches all transactions for a specific card according to the query parameters.", "operationId": "get-card-transactions", "parameters": [{ "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of transactions to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "fromDate", "in": "query", "description": "This is the start date of the date range.", "schema": { "type": "string", "format": "date" } }, { "name": "toDate", "in": "query", "description": "This is the end date of the date range.", "schema": { "type": "string", "format": "date" } }, { "name": "id", "in": "path", "description": "The `_id` of the card you wish to fetch the transactions for.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Transactions fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "status": { "type": "string", "description": "Current status of the object." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "format": "date-time", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "failedTransactionCount": { "type": "integer" }, "minimumBalance": { "type": "integer" }, "version": { "type": "string" }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "program": { "nullable": true }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "status": { "type": "string", "description": "Current status of the object." }, "is2FAEnabled": { "type": "boolean" }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "providerReference": { "type": "string" }, "isDigitalized": { "type": "boolean" }, "accumulatedFees": { "type": "integer" }, "totalFeesCharged": { "type": "integer" }, "feeChargeDay": { "type": "integer" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": {} } } } } }, "authorization": { "type": "object", "description": "Identifier of the authorization this transaction belongs to.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "card": { "type": "string", "description": "Associated card \u2014 an id, or a summary object on nested resources." }, "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "number", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "pendingRequest": { "nullable": true, "description": "Details of the amount currently being authorized." }, "requestHistory": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." } } } }, "verification": { "type": "object", "properties": { "billingAddressLine1": { "type": "string" }, "billingAddressPostalCode": { "type": "string" }, "cvv": { "type": "string" }, "expiry": { "type": "string" }, "pin": { "type": "string" }, "threeDSecure": { "type": "string" }, "safeToken": { "type": "string" }, "authentication": { "type": "string" } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "amount": { "type": "number", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "number", "description": "VAT charged, in the minor currency unit." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "type": { "type": "string", "description": "Type of the object." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Transactions fetched successfully.", "data": [ { "_id": "6a43ba8d134c39198fe2167d", "business": "696edb9889c90df3bcdbe067", "customer": { "_id": "69ba46bb734a4457f2d063f5", "business": "696edb9889c90df3bcdbe067", "type": "individual", "name": "Prince Muteh", "phoneNumber": "7030338024", "emailAddress": "prince.muteh@gmail.com", "status": "active", "individual": { "firstName": "Prince", "lastName": "Muteh", "otherNames": "", "dob": "2026-03-18T00:00:00.000Z", "identity": { "type": "BVN", "number": "1234567890" } }, "billingAddress": { "line1": "University Of Maiduguri", "line2": "", "city": "Garki", "state": "Abuja Federal Capital Territory", "country": "Nigeria", "postalCode": "600211" }, "isDeleted": false, "createdAt": "2026-03-18T06:31:23.112Z", "updatedAt": "2026-03-18T06:31:23.112Z", "__v": 0 }, "account": { "_id": "69ba46d6734a4457f2d06428", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRINCE MUTEH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010251947", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "69ba46d6012c2100246f7a38", "referenceCode": "subacc_1773815509991", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-03-18T06:31:50.409Z", "updatedAt": "2026-03-18T06:31:50.409Z", "charges": [], "__v": 0 }, "card": { "failedTransactionCount": 0, "minimumBalance": 0, "version": "v1", "_id": "69ba46d8734a4457f2d06430", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "fundingSource": "69ba4677734a4457f2d06383", "program": null, "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506321*********3111", "expiryMonth": "03", "expiryYear": "2029", "status": "active", "is2FAEnabled": true, "is2FAEnrolled": true, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "providerReference": "69ba46d8a61d0550d690e79e", "isDigitalized": false, "accumulatedFees": 0, "totalFeesCharged": 0, "feeChargeDay": 1, "isDeleted": false, "createdAt": "2026-03-18T06:31:52.457Z", "updatedAt": "2026-06-30T12:55:52.640Z", "__v": 0, "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [] } }, "authorization": { "_id": "6a43ba89134c39198fe21652", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "card": "69ba46d8734a4457f2d06430", "amount": 10005.38, "fee": 5, "vat": 0.38, "approved": true, "currency": "NGN", "status": "approved", "authorizationMethod": "online", "balanceTransactions": [], "merchantAmount": 10000, "merchantCurrency": "NGN", "merchant": { "category": "0742", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "149283196621", "stan": "148345", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947149283196621" }, "pendingRequest": null, "requestHistory": [ { "amount": 10005.38, "currency": "NGN", "approved": true, "merchantAmount": 10000, "merchantCurrency": "NGN", "reason": "webhook_approved", "createdAt": "2026-06-30T12:46:01.932Z" } ], "verification": { "billingAddressLine1": "not_provided", "billingAddressPostalCode": "not_provided", "cvv": "match", "expiry": "match", "pin": "match", "threeDSecure": "not_provided", "safeToken": "match", "authentication": "pin" }, "isDeleted": false, "createdAt": "2026-06-30T12:46:01.932Z", "updatedAt": "2026-06-30T12:46:01.932Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" } ], "__v": 1 }, "amount": -10005.38, "fee": -5, "vat": -0.38, "currency": "NGN", "type": "capture", "balanceTransactions": [], "merchantAmount": -10000, "merchantCurrency": "NGN", "merchant": { "category": "0742", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "149283196621", "stan": "148345", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947149283196621" }, "isDeleted": false, "createdAt": "2026-06-30T12:46:05.398Z", "updatedAt": "2026-06-30T12:46:05.398Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" }, null ], "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/transactions/{id}": { "get": { "summary": "Get Transaction", "description": "Fetches details about a specific transaction using the provided id.", "operationId": "get-transaction", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the transaction to fetch.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Transaction fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "status": { "type": "string", "description": "Current status of the object." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "format": "date-time", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "failedTransactionCount": { "type": "integer" }, "minimumBalance": { "type": "integer" }, "version": { "type": "string" }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "program": { "nullable": true }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "status": { "type": "string", "description": "Current status of the object." }, "is2FAEnabled": { "type": "boolean" }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "providerReference": { "type": "string" }, "isDigitalized": { "type": "boolean" }, "accumulatedFees": { "type": "integer" }, "totalFeesCharged": { "type": "integer" }, "feeChargeDay": { "type": "integer" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": {} } } } } }, "authorization": { "type": "object", "description": "Identifier of the authorization this transaction belongs to.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "card": { "type": "string", "description": "Associated card \u2014 an id, or a summary object on nested resources." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "integer", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "pendingRequest": { "nullable": true, "description": "Details of the amount currently being authorized." }, "requestHistory": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." } } } }, "verification": { "type": "object", "properties": { "billingAddressLine1": { "type": "string" }, "billingAddressPostalCode": { "type": "string" }, "cvv": { "type": "string" }, "expiry": { "type": "string" }, "pin": { "type": "string" }, "threeDSecure": { "type": "string" }, "safeToken": { "type": "string" }, "authentication": { "type": "string" } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "integer", "description": "VAT charged, in the minor currency unit." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "type": { "type": "string", "description": "Type of the object." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Transaction fetched successfully.", "data": { "_id": "69c0087e144d27053ad73f43", "business": "696edb9889c90df3bcdbe067", "customer": { "_id": "69ba46bb734a4457f2d063f5", "business": "696edb9889c90df3bcdbe067", "type": "individual", "name": "Prince Muteh", "phoneNumber": "7030338024", "emailAddress": "prince.muteh@gmail.com", "status": "active", "individual": { "firstName": "Prince", "lastName": "Muteh", "otherNames": "", "dob": "2026-03-18T00:00:00.000Z", "identity": { "type": "BVN", "number": "1234567890" } }, "billingAddress": { "line1": "University Of Maiduguri", "line2": "", "city": "Garki", "state": "Abuja Federal Capital Territory", "country": "Nigeria", "postalCode": "600211" }, "isDeleted": false, "createdAt": "2026-03-18T06:31:23.112Z", "updatedAt": "2026-03-18T06:31:23.112Z", "__v": 0 }, "account": { "_id": "69ba46d6734a4457f2d06428", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRINCE MUTEH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010251947", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "69ba46d6012c2100246f7a38", "referenceCode": "subacc_1773815509991", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-03-18T06:31:50.409Z", "updatedAt": "2026-03-18T06:31:50.409Z", "charges": [], "__v": 0 }, "card": { "failedTransactionCount": 0, "minimumBalance": 0, "version": "v1", "_id": "69ba46d8734a4457f2d06430", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "fundingSource": "69ba4677734a4457f2d06383", "program": null, "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506321*********3111", "expiryMonth": "03", "expiryYear": "2029", "status": "active", "is2FAEnabled": true, "is2FAEnrolled": true, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "providerReference": "69ba46d8a61d0550d690e79e", "isDigitalized": false, "accumulatedFees": 0, "totalFeesCharged": 0, "feeChargeDay": 1, "isDeleted": false, "createdAt": "2026-03-18T06:31:52.457Z", "updatedAt": "2026-06-05T14:10:59.140Z", "__v": 0, "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [] } }, "authorization": { "_id": "69c00879144d27053ad73f33", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "card": "69ba46d8734a4457f2d06430", "amount": 1005, "fee": 5, "vat": 0, "approved": true, "currency": "NGN", "status": "approved", "authorizationMethod": "online", "balanceTransactions": [], "merchantAmount": 1000, "merchantCurrency": "NGN", "merchant": { "category": "0763", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "195930677510", "stan": "124499", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947195930677510" }, "pendingRequest": null, "requestHistory": [ { "amount": 1005, "currency": "NGN", "approved": true, "merchantAmount": 1000, "merchantCurrency": "NGN", "reason": "webhook_approved", "createdAt": "2026-03-22T15:19:21.165Z" } ], "verification": { "billingAddressLine1": "not_provided", "billingAddressPostalCode": "not_provided", "cvv": "match", "expiry": "match", "pin": "match", "threeDSecure": "not_provided", "safeToken": "match", "authentication": "pin" }, "isDeleted": false, "createdAt": "2026-03-22T15:19:21.165Z", "updatedAt": "2026-03-22T15:19:21.165Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" } ], "__v": 1 }, "amount": -1005, "fee": -5, "vat": 0, "currency": "NGN", "type": "capture", "balanceTransactions": [], "merchantAmount": -1000, "merchantCurrency": "NGN", "merchant": { "category": "0763", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "195930677510", "stan": "124499", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947195930677510" }, "isDeleted": false, "createdAt": "2026-03-22T15:19:26.112Z", "updatedAt": "2026-03-22T15:19:26.112Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" }, null ], "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid transaction id.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Transaction not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "put": { "summary": "Update Transaction", "description": "Fetches details about a specific transaction using the provided id.", "operationId": "update-transaction", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the transaction to fetch.", "schema": { "type": "string" }, "required": true }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "string", "description": "The key-value pair you wish to attach to the transaction object.", "default": "{}", "format": "json" } } } } } }, "responses": { "200": { "description": "Transaction updated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "object", "description": "Associated customer \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "name": { "type": "string", "description": "Display name." }, "phoneNumber": { "type": "string", "description": "Customer's phone number in international format." }, "emailAddress": { "type": "string", "description": "Customer's email address." }, "status": { "type": "string", "description": "Current status of the object." }, "individual": { "type": "object", "description": "Details for an individual customer.", "properties": { "firstName": { "type": "string", "description": "First name." }, "lastName": { "type": "string", "description": "Last name." }, "otherNames": { "type": "string", "description": "Other names, if any." }, "dob": { "type": "string", "format": "date-time", "description": "Date of birth (YYYY/MM/DD)." }, "identity": { "type": "object", "description": "Customer's verified identity record.", "properties": { "type": { "type": "string", "description": "Type of the object." }, "number": { "type": "string", "description": "Identity / card number value." } } } } }, "billingAddress": { "type": "object", "description": "Customer's billing address.", "properties": { "line1": { "type": "string", "description": "Address line 1." }, "line2": { "type": "string", "description": "Address line 2." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "account": { "type": "object", "description": "Associated account \u2014 an id, or a summary object on nested resources.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "accountName": { "type": "string", "description": "Name on the account." }, "bankCode": { "type": "string", "description": "Bank / institution code." }, "accountType": { "type": "string", "description": "Account product type (`Savings` or `Current`)." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "currentBalance": { "type": "integer", "description": "Current ledger balance, in the minor currency unit." }, "availableBalance": { "type": "integer", "description": "Balance available for spending, in the minor currency unit." }, "provider": { "type": "string", "description": "Underlying provider backing the object." }, "providerReference": { "type": "string" }, "referenceCode": { "type": "string" }, "reloadable": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "charges": { "type": "array", "items": {} }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "card": { "type": "object", "description": "Associated card \u2014 an id, or a summary object on nested resources.", "properties": { "failedTransactionCount": { "type": "integer" }, "minimumBalance": { "type": "integer" }, "version": { "type": "string" }, "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "fundingSource": { "type": "string", "description": "Identifier of the funding source backing this object." }, "program": { "nullable": true }, "type": { "type": "string", "description": "Type of the object." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "maskedPan": { "type": "string", "description": "Masked card number (PAN)." }, "expiryMonth": { "type": "string", "description": "Card expiry month (MM)." }, "expiryYear": { "type": "string", "description": "Card expiry year (YYYY)." }, "status": { "type": "string", "description": "Current status of the object." }, "is2FAEnabled": { "type": "boolean" }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." }, "disposable": { "type": "boolean", "description": "Whether the card is single-use / disposable." }, "refundAccount": { "nullable": true, "description": "Account to which refunds are routed, if any." }, "providerReference": { "type": "string" }, "isDigitalized": { "type": "boolean" }, "accumulatedFees": { "type": "integer" }, "totalFeesCharged": { "type": "integer" }, "feeChargeDay": { "type": "integer" }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." }, "spendingControls": { "type": "object", "description": "Spending limits and channel/category controls applied to the card.", "properties": { "channels": { "type": "object", "description": "Channels through which the card may be used.", "properties": { "atm": { "type": "boolean", "description": "Whether ATM usage is allowed." }, "pos": { "type": "boolean", "description": "Whether POS usage is allowed." }, "web": { "type": "boolean", "description": "Whether web/online usage is allowed." }, "mobile": { "type": "boolean", "description": "Whether mobile usage is allowed." } } }, "allowedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly allowed.", "items": {} }, "blockedCategories": { "type": "array", "description": "Merchant category codes (MCC) explicitly blocked.", "items": {} }, "spendingLimits": { "type": "array", "description": "Configured spending limits.", "items": {} } } } } }, "authorization": { "type": "object", "description": "Identifier of the authorization this transaction belongs to.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "customer": { "type": "string", "description": "Associated customer \u2014 an id, or a summary object on nested resources." }, "account": { "type": "string", "description": "Associated account \u2014 an id, or a summary object on nested resources." }, "card": { "type": "string", "description": "Associated card \u2014 an id, or a summary object on nested resources." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "integer", "description": "VAT charged, in the minor currency unit." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "status": { "type": "string", "description": "Current status of the object." }, "authorizationMethod": { "type": "string", "description": "How the authorization was performed." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "pendingRequest": { "nullable": true, "description": "Details of the amount currently being authorized." }, "requestHistory": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "approved": { "type": "boolean", "description": "Whether the authorization was approved." }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." } } } }, "verification": { "type": "object", "properties": { "billingAddressLine1": { "type": "string" }, "billingAddressPostalCode": { "type": "string" }, "cvv": { "type": "string" }, "expiry": { "type": "string" }, "pin": { "type": "string" }, "threeDSecure": { "type": "string" }, "safeToken": { "type": "string" }, "authentication": { "type": "string" } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "vat": { "type": "integer", "description": "VAT charged, in the minor currency unit." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "type": { "type": "string", "description": "Type of the object." }, "balanceTransactions": { "type": "array", "items": {} }, "merchantAmount": { "type": "integer", "description": "Amount in the merchant's currency." }, "merchantCurrency": { "type": "string", "description": "Merchant's ISO 4217 currency code." }, "merchant": { "type": "object", "properties": { "category": { "type": "string" }, "name": { "type": "string", "description": "Display name." }, "merchantId": { "type": "string" }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State / region." }, "country": { "type": "string", "description": "Country." }, "postalCode": { "type": "string", "description": "Postal / ZIP code." } } }, "terminal": { "type": "object", "properties": { "rrn": { "type": "string" }, "stan": { "type": "string" }, "terminalId": { "type": "string" }, "terminalOperatingEnvironment": { "type": "string" }, "terminalAttendance": { "type": "string" }, "terminalType": { "type": "string" }, "panEntryMode": { "type": "string" }, "pinEntryMode": { "type": "string" }, "cardHolderPresence": { "type": "boolean" }, "cardPresence": { "type": "boolean" } } }, "transactionMetadata": { "type": "object", "description": "Channel and reference metadata for the transaction.", "properties": { "channel": { "type": "string", "description": "Channel the transaction occurred on (`web`, `pos`, `atm`)." }, "type": { "type": "string", "description": "Type of the object." }, "reference": { "type": "string", "description": "Unique reference assigned to the object." } } }, "isDeleted": { "type": "boolean", "description": "Whether the object has been soft-deleted." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "feeDetails": { "type": "array", "items": { "type": "object", "properties": { "contract": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `NGN`)." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "description": { "type": "string", "description": "Description text." } } } }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Transaction updated successfully.", "data": { "_id": "69c0087e144d27053ad73f43", "business": "696edb9889c90df3bcdbe067", "customer": { "_id": "69ba46bb734a4457f2d063f5", "business": "696edb9889c90df3bcdbe067", "type": "individual", "name": "Prince Muteh", "phoneNumber": "7030338024", "emailAddress": "prince.muteh@gmail.com", "status": "active", "individual": { "firstName": "Prince", "lastName": "Muteh", "otherNames": "", "dob": "2026-03-18T00:00:00.000Z", "identity": { "type": "BVN", "number": "1234567890" } }, "billingAddress": { "line1": "University Of Maiduguri", "line2": "", "city": "Garki", "state": "Abuja Federal Capital Territory", "country": "Nigeria", "postalCode": "600211" }, "isDeleted": false, "createdAt": "2026-03-18T06:31:23.112Z", "updatedAt": "2026-03-18T06:31:23.112Z", "__v": 0 }, "account": { "_id": "69ba46d6734a4457f2d06428", "business": "696edb9889c90df3bcdbe067", "type": "wallet", "currency": "NGN", "accountName": "SUDO / PRINCE MUTEH", "bankCode": "999240", "accountType": "Current", "accountNumber": "5010251947", "currentBalance": 0, "availableBalance": 0, "provider": "SafeHaven", "providerReference": "69ba46d6012c2100246f7a38", "referenceCode": "subacc_1773815509991", "reloadable": true, "isDefault": true, "isDeleted": false, "createdAt": "2026-03-18T06:31:50.409Z", "updatedAt": "2026-03-18T06:31:50.409Z", "charges": [], "__v": 0 }, "card": { "failedTransactionCount": 0, "minimumBalance": 0, "version": "v1", "_id": "69ba46d8734a4457f2d06430", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "fundingSource": "69ba4677734a4457f2d06383", "program": null, "type": "virtual", "brand": "Verve", "currency": "NGN", "maskedPan": "506321*********3111", "expiryMonth": "03", "expiryYear": "2029", "status": "active", "is2FAEnabled": true, "is2FAEnrolled": true, "isDefaultPINChanged": false, "disposable": false, "refundAccount": null, "providerReference": "69ba46d8a61d0550d690e79e", "isDigitalized": false, "accumulatedFees": 0, "totalFeesCharged": 0, "feeChargeDay": 1, "isDeleted": false, "createdAt": "2026-03-18T06:31:52.457Z", "updatedAt": "2026-06-05T14:10:59.140Z", "__v": 0, "spendingControls": { "channels": { "atm": true, "pos": true, "web": true, "mobile": true }, "allowedCategories": [], "blockedCategories": [], "spendingLimits": [] } }, "authorization": { "_id": "69c00879144d27053ad73f33", "business": "696edb9889c90df3bcdbe067", "customer": "69ba46bb734a4457f2d063f5", "account": "69ba46d6734a4457f2d06428", "card": "69ba46d8734a4457f2d06430", "amount": 1005, "fee": 5, "vat": 0, "approved": true, "currency": "NGN", "status": "approved", "authorizationMethod": "online", "balanceTransactions": [], "merchantAmount": 1000, "merchantCurrency": "NGN", "merchant": { "category": "0763", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "195930677510", "stan": "124499", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947195930677510" }, "pendingRequest": null, "requestHistory": [ { "amount": 1005, "currency": "NGN", "approved": true, "merchantAmount": 1000, "merchantCurrency": "NGN", "reason": "webhook_approved", "createdAt": "2026-03-22T15:19:21.165Z" } ], "verification": { "billingAddressLine1": "not_provided", "billingAddressPostalCode": "not_provided", "cvv": "match", "expiry": "match", "pin": "match", "threeDSecure": "not_provided", "safeToken": "match", "authentication": "pin" }, "isDeleted": false, "createdAt": "2026-03-22T15:19:21.165Z", "updatedAt": "2026-03-22T15:19:21.165Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" } ], "__v": 1 }, "amount": -1005, "fee": -5, "vat": 0, "currency": "NGN", "type": "capture", "balanceTransactions": [], "merchantAmount": -1000, "merchantCurrency": "NGN", "merchant": { "category": "0763", "name": "SUDO SIMULATOR", "merchantId": "SUDOSIMULATOR01", "city": "JAHI", "state": "AB", "country": "NG", "postalCode": "100001" }, "terminal": { "rrn": "195930677510", "stan": "124499", "terminalId": "3SUDOSIM", "terminalOperatingEnvironment": "on_premise", "terminalAttendance": "unattended", "terminalType": "ecommerce", "panEntryMode": "keyed_in", "pinEntryMode": "keyed_in", "cardHolderPresence": true, "cardPresence": true }, "transactionMetadata": { "channel": "web", "type": "purchase", "reference": "5010251947195930677510" }, "isDeleted": false, "createdAt": "2026-03-22T15:19:26.112Z", "updatedAt": "2026-03-22T15:19:26.112Z", "feeDetails": [ { "contract": "61a18b8a4ddab599d20344a7", "currency": "NGN", "amount": 5, "description": "Verve Card Authorization Fee" }, null ], "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid metadata.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Transaction not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/disputes": { "post": { "summary": "Create Dispute", "description": "Creates a dispute for a specific transaction.", "operationId": "create-dispute", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["transactionId", "reason", "explanation"], "properties": { "transactionId": { "type": "string", "description": "The `_id` of the transaction the dispute is for." }, "reason": { "type": "string", "description": "The reason for the dispute.", "default": "not_received", "enum": ["not_received", "fraudulent", "duplicate", "product_not_as_described", "service_not_as_described", "canceled", "other"] }, "explanation": { "type": "string", "description": "More details on the dispute." }, "metadata": { "type": "string", "description": "The key-value pair you wish to attach to the dispute object.", "default": "{}", "format": "json" } } } } } }, "responses": { "201": { "description": "Dispute created successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "transaction": { "type": "string", "description": "Identifier of the transaction." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "explanation": { "type": "string", "description": "Additional explanation supplied with the dispute." }, "status": { "type": "string", "description": "Current status of the object." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": {} }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Dispute created successfully.", "data": { "_id": "6840c1aa2b3c4d5e6f700444", "business": "670cec9d25852ba485d74273", "transaction": "6840c1aa2b3c4d5e6f700333", "reason": "fraudulent", "explanation": "Customer did not authorize this transaction.", "status": "pending", "metadata": {}, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"transactionId\" is required", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "get": { "summary": "Get Disputes", "description": "Fetches all disputes according to the query parameters.", "operationId": "get-disputes", "parameters": [{ "name": "page", "in": "query", "description": "Specifies the position the response data should begin from.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "limit", "in": "query", "description": "The number of transactions to fetch.", "schema": { "type": "integer", "format": "int32", "default": 100 } }], "responses": { "200": { "description": "Disputes fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "transaction": { "type": "string", "description": "Identifier of the transaction." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "explanation": { "type": "string", "description": "Additional explanation supplied with the dispute." }, "status": { "type": "string", "description": "Current status of the object." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": {} }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } }, "pagination": { "type": "object", "description": "Pagination metadata for the result set.", "properties": { "total": { "type": "integer", "description": "Total number of records matching the query across all pages." }, "pages": { "type": "integer", "description": "Total number of pages available for the current query." }, "page": { "type": "integer", "description": "Current page index (zero-based; matches the `page` query parameter)." }, "limit": { "type": "integer", "description": "Maximum number of records returned per page (matches the `limit` query parameter)." } } } } }, "example": { "statusCode": 200, "message": "Disputes fetched successfully.", "data": [ { "_id": "6840c1aa2b3c4d5e6f700444", "business": "670cec9d25852ba485d74273", "transaction": "6840c1aa2b3c4d5e6f700333", "reason": "fraudulent", "explanation": "Customer did not authorize this transaction.", "status": "pending", "metadata": {}, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } ], "pagination": { "total": 8, "pages": 1, "page": 0, "limit": 50 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid pagination parameters.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/disputes/{id}": { "get": { "summary": "Get Dispute", "description": "Fetches details about a specific dispute using the provided id.", "operationId": "get-dispute", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the dispute to fetch.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Dispute fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "transaction": { "type": "string", "description": "Identifier of the transaction." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "explanation": { "type": "string", "description": "Additional explanation supplied with the dispute." }, "status": { "type": "string", "description": "Current status of the object." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": {} }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Dispute fetched successfully.", "data": { "_id": "6840c1aa2b3c4d5e6f700444", "business": "670cec9d25852ba485d74273", "transaction": "6840c1aa2b3c4d5e6f700333", "reason": "fraudulent", "explanation": "Customer did not authorize this transaction.", "status": "pending", "metadata": {}, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid dispute id.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Dispute not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false }, "put": { "summary": "Update Dispute", "description": "Updates a dispute for a specific transaction.", "operationId": "update-dispute", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the transaction to fetch.", "schema": { "type": "string" }, "required": true }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["reason", "explanation"], "properties": { "reason": { "type": "string", "description": "The reason for the dispute.", "default": "not_received", "enum": ["not_received", "fraudulent", "duplicate", "product_not_as_described", "service_not_as_described", "canceled", "other"] }, "explanation": { "type": "string", "description": "More details on the dispute." }, "metadata": { "type": "string", "description": "The key-value pair you wish to attach to the dispute object.", "default": "{}", "format": "json" } } } } } }, "responses": { "200": { "description": "Dispute updated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "transaction": { "type": "string", "description": "Identifier of the transaction." }, "reason": { "type": "string", "description": "Reason for the dispute." }, "explanation": { "type": "string", "description": "Additional explanation supplied with the dispute." }, "status": { "type": "string", "description": "Current status of the object." }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs attached to the object.", "properties": {} }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." }, "__v": { "type": "integer", "description": "Internal document version (Mongo)." } } } } }, "example": { "statusCode": 200, "message": "Dispute updated successfully.", "data": { "_id": "6840c1aa2b3c4d5e6f700444", "business": "670cec9d25852ba485d74273", "transaction": "6840c1aa2b3c4d5e6f700333", "reason": "fraudulent", "explanation": "Customer did not authorize this transaction.", "status": "pending", "metadata": {}, "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z", "__v": 0 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"reason\" must be a valid dispute reason", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Dispute not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/customers/{id}/documents/url": { "put": { "summary": "Generate Customer Document URL", "description": "Generate a document upload URL for a specific customer KYC.", "operationId": "generate-customer-document-url", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the customer you wish to upload documents for.", "schema": { "type": "string" }, "required": true }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["fileName", "fileType"], "properties": { "fileName": { "type": "string", "description": "Name of file to be uploaded." }, "fileType": { "type": "string", "description": "File MIME type e.g `image/png`" } } } } } }, "responses": { "200": { "description": "Pre-signed upload URL generated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "url": { "type": "string", "description": "URL value." }, "key": { "type": "string", "description": "Storage object key for the uploaded file." } } } } }, "example": { "statusCode": 200, "message": "Document upload url generated successfully.", "data": { "url": "https://sudo-documents.s3.amazonaws.com/customers/64a1b2c3d4e5f6a7b8c9d0e1/id-front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA...%2F20240906%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20240906T123456Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=4f8c1234567890abcdef", "key": "customers/64a1b2c3d4e5f6a7b8c9d0e1/id-front.png" } } } } }, "400": { "description": "Validation error \u2014 fileName/fileType missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"fileType\" is required", "data": null } } } }, "404": { "description": "No customer exists with the supplied id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Customer not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/{id}/pin": { "put": { "summary": "Change Card PIN", "description": "Change PIN for a specific card. Available for both Verve and AfriGo (physical and virtual) cards.", "operationId": "change-card-pin", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the card to update.", "schema": { "type": "string" }, "required": true }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["oldPin", "newPin"], "properties": { "oldPin": { "type": "string", "description": "4 digits old card PIN." }, "newPin": { "type": "string", "description": "4 digits new card PIN." } } } } } }, "responses": { "200": { "description": "Card PIN changed successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "isDefaultPINChanged": { "type": "boolean", "description": "Whether the default PIN has been changed." } } } } }, "example": { "statusCode": 200, "message": "Card PIN changed successfully.", "data": { "_id": "6418eb71a37e405064694518", "isDefaultPINChanged": true } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Incorrect old PIN.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/{id}/token": { "get": { "summary": "Generate Card Token", "description": "This endpoint generates a card token to be used for displaying sensitive card data.", "operationId": "generate-card-token", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the card to generate the token for.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Card token generated successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "token": { "type": "string", "description": "Short-lived JWT used to render secure card data on the client." } } } } }, "example": { "statusCode": 200, "message": "Card token generated successfully.", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2NDE4ZWI3MWEzN2U0MDUwNjQ2OTQ1MTgiLCJ0eXBlIjoiQ0FSRFRPS0VOIiwiaWF0IjoxNzA3NzE4ODk2LCJleHAiOjE3MDc3MTkwMTZ9.Cj-Q21HKgUCOFvC3l7JQc0OZdoW932TEeeAFK6GEOGQ" } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/transfers/{transferId}": { "get": { "summary": "Get Transfer Status", "description": "Returns the status of a transfer.", "operationId": "get-transfer-status", "parameters": [{ "name": "transferId", "in": "path", "description": "_id of transfer from Fund Transfer endpoint.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Transfer status fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "business": { "type": "string", "description": "Identifier of the business that owns this object." }, "type": { "type": "string", "description": "Type of the object." }, "debitAccountId": { "type": "string", "description": "Identifier of the account/wallet/card debited." }, "creditAccountId": { "nullable": true, "description": "Identifier of the internal account credited, or `null` for external transfers." }, "beneficiaryBankCode": { "type": "string", "description": "Beneficiary bank code." }, "beneficiaryAccountNumber": { "type": "string", "description": "Beneficiary account number." }, "beneficiaryAccountName": { "type": "string", "description": "Resolved beneficiary account name." }, "amount": { "type": "integer", "description": "Amount in the minor currency unit (e.g. kobo)." }, "fee": { "type": "integer", "description": "Fee charged, in the minor currency unit." }, "narration": { "type": "string", "description": "Transfer narration / description." }, "paymentReference": { "type": "string", "description": "Client-supplied unique payment reference." }, "sessionId": { "type": "string", "description": "NIP session identifier for the transfer." }, "status": { "type": "string", "description": "Current status of the object." }, "responseCode": { "type": "string", "description": "Transfer response code (`00` indicates success)." }, "responseMessage": { "type": "string", "description": "Human-readable transfer response message." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the object was last updated." } } } } }, "example": { "statusCode": 200, "message": "Transfer status fetched successfully.", "data": { "_id": "6840c1aa2b3c4d5e6f700555", "business": "670cec9d25852ba485d74273", "type": "Transfer", "debitAccountId": "67974b365c184d20fc340889", "creditAccountId": null, "beneficiaryBankCode": "000014", "beneficiaryAccountNumber": "0123456789", "beneficiaryAccountName": "JANE DOE", "amount": 5000, "fee": 10, "narration": "Payment for services", "paymentReference": "REF-250604-2156", "sessionId": "090286250604215600123456789012", "status": "completed", "responseCode": "00", "responseMessage": "Approved or completed successfully", "createdAt": "2025-06-04T21:05:26.115Z", "updatedAt": "2025-06-05T09:15:00.000Z" } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid transfer id.", "data": null } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 404, "message": "Transfer not found.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/{id}/send-pin": { "put": { "summary": "Send Default Card PIN", "description": "Send Default PIN for a specific card. Only available for Verve and AfriGo cards at the moment.", "operationId": "send-default-card-pin", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the card to update.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Card PIN sent successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "sent": { "type": "boolean", "description": "Whether the PIN SMS was sent." } } } } }, "example": { "statusCode": 200, "message": "Card PIN sent successfully.", "data": { "_id": "6418eb71a37e405064694518", "sent": true } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/order": { "post": { "summary": "Order Cards", "description": "Order Physical Cards", "operationId": "order-cards", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["debitAccountId", "brand", "currency", "allocation", "expedite", "shippingMethod", "shippingAddress"], "properties": { "debitAccountId": { "type": "string", "description": "The debit account `_id`." }, "customerId": { "type": "string", "description": "The customer `_id`. Required if creating 1 card" }, "brand": { "type": "string", "description": "The card brand.", "enum": ["Verve", "AfriGo", "MasterCard", "Visa"] }, "currency": { "type": "string", "description": "The currency type.", "default": "NGN", "enum": ["NGN", "USD"] }, "design": { "type": "string", "description": "The name of the card design. Ask Customer support for your own design name.", "default": "SudoBlack", "enum": ["SudoBlack", "SudoWhite", "[YourDesignName]"] }, "allocation": { "type": "integer", "description": "The number of physical cards to order.", "default": 1, "format": "int32" }, "nameOnCards": { "type": "array", "description": "Array of names to be personalized on the cards.", "items": { "type": "string" } }, "expedite": { "type": "boolean", "description": "The expedite preference.", "default": false }, "shippingMethod": { "type": "string", "description": "The shipping method to use. Might impact card cost. Ask Customer Support for guidance.", "default": "NIPOST", "enum": ["NIPOST", "DHL"] }, "shippingAddress": { "type": "object", "description": "The cards shipping address.", "required": ["line1", "city", "state", "postalCode", "country"], "properties": { "line1": { "type": "string", "description": "Street address line 1" }, "line2": { "type": "string", "description": "Street Address line 2" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State" }, "postalCode": { "type": "string" }, "country": { "type": "string", "description": "Billing country" } } } } } } } }, "responses": { "201": { "description": "Cards ordered successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "batchReference": { "type": "string", "description": "Reference for the card order batch." }, "allocation": { "type": "integer", "description": "Number of cards in the order." }, "brand": { "type": "string", "description": "Card scheme/brand (e.g. `Verve`, `MasterCard`)." }, "status": { "type": "string", "description": "Current status of the object." } } } } }, "example": { "statusCode": 200, "message": "Cards ordered successfully.", "data": { "batchReference": "ORD-250604-2156", "allocation": 5, "brand": "Verve", "status": "processing" } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "\"customerId\" is required", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/transfer/name-enquiry": { "post": { "summary": "Name Enquiry", "description": "Gets the bank account name on a given account.", "operationId": "name-enquiry", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["bankCode", "accountNumber"], "properties": { "bankCode": { "type": "string", "description": "The bank code of the bank for the account you want to perform an enquiry for." }, "accountNumber": { "type": "string", "description": "The account number of the account to perform the enquiry for." } } } } } }, "responses": { "200": { "description": "Account name fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "accountName": { "type": "string", "description": "Name on the account." }, "accountNumber": { "type": "string", "description": "Account number (NUBAN)." }, "bankCode": { "type": "string", "description": "Bank / institution code." } } } } }, "example": { "statusCode": 200, "message": "Account name fetched successfully.", "data": { "accountName": "JANE DOE", "accountNumber": "0123456789", "bankCode": "000014" } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Could not resolve account name.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/banks": { "get": { "summary": "Banks List", "description": "Gets the list of banks for a given country.", "operationId": "banks-list", "parameters": [{ "name": "country", "in": "query", "description": "Country Code.", "schema": { "type": "string", "default": "NG" } }], "responses": { "200": { "description": "Banks fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "array", "description": "Array of objects for the requested page.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name." }, "code": { "type": "string", "description": "Bank / institution code." }, "type": { "type": "string", "description": "Type of the object." } } } } } }, "example": { "statusCode": 200, "message": "Banks fetched successfully.", "data": [ { "name": "Access Bank", "code": "000014", "type": "nuban" }, { "name": "Guaranty Trust Bank", "code": "000013", "type": "nuban" }, { "name": "Zenith Bank", "code": "000015", "type": "nuban" } ] } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Could not fetch banks.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/cards/{id}/enroll2fa": { "put": { "summary": "Enroll Card for 2FA", "description": "Enroll 2FA for a specific card. Only available for Verve and AfriGo cards at the moment.", "operationId": "enroll-card-for-2fa", "parameters": [{ "name": "id", "in": "path", "description": "The `_id` of the card to update.", "schema": { "type": "string" }, "required": true }], "responses": { "200": { "description": "Card enrolled for 2FA successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "_id": { "type": "string", "description": "Unique identifier of the object." }, "is2FAEnrolled": { "type": "boolean", "description": "Whether the card is enrolled for 3-D Secure / 2FA." } } } } }, "example": { "statusCode": 200, "message": "Card enrolled for 2FA successfully.", "data": { "_id": "6418eb71a37e405064694518", "is2FAEnrolled": true } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid card id.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } }, "/accounts/transfer/rate/{currencyPair}": { "get": { "summary": "Transfer Rate", "description": "Returns the exchange rate between two currency pairs. Currently supports `USDNGN` only.", "operationId": "transfer-rate", "parameters": [{ "name": "currencyPair", "in": "path", "description": "Exchange Currency Pair. Example `USDNGN`.", "schema": { "type": "string", "default": "USDNGN" }, "required": true }], "responses": { "200": { "description": "Exchange rate fetched successfully.", "headers": { "X-Powered-By": { "schema": { "type": "string" }, "example": "Express" }, "Access-Control-Allow-Origin": { "schema": { "type": "string" }, "example": "*" }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "example": "250000" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "example": "249999" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "example": "0" }, "Content-Type": { "schema": { "type": "string" }, "example": "application/json; charset=utf-8" }, "ETag": { "schema": { "type": "string" }, "example": "W/\"2dd-sfRBgLV2BqnKnzwqFCi2UGdBgUQ\"" }, "Connection": { "schema": { "type": "string" }, "example": "keep-alive" }, "Keep-Alive": { "schema": { "type": "string" }, "example": "timeout=5" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "type": "object", "description": "Response payload.", "properties": { "rate": { "type": "string", "description": "Applicable exchange rate." }, "sell": { "type": "string", "description": "Sell rate." }, "buy": { "type": "string", "description": "Buy rate." } } } } }, "example": { "statusCode": 200, "message": "Exchange rate fetched successfully.", "data": { "rate": "530.00", "sell": "482.00", "buy": "530.00" } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Always `null` for error responses." } } }, "example": { "statusCode": 400, "message": "Invalid currency pair.", "data": null } } } }, "401": { "description": "Authentication failed \u2014 missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "Status code of the response. `200` indicates a successful request." }, "message": { "type": "string", "description": "Human-readable description of the result." }, "data": { "nullable": true, "description": "Response payload." } } }, "example": { "statusCode": 401, "message": "Unauthorized. Provide a valid API key in the Authorization header.", "data": null } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true }