{ "openapi": "3.0.1", "info": { "description": "", "title": "Vendor API", "version": "1.0.0" }, "servers": [ { "description": "Production", "url": "https://api.nomba.com" }, { "description": "Sandbox", "url": "https://sandbox.nomba.com" } ], "tags": [ { "name": "Authenticate" }, { "name": "Accounts" }, { "name": "Virtual Accounts" }, { "name": "Online Checkout" }, { "name": "Charge" }, { "name": "Transfers" }, { "name": "Direct Debits" }, { "name": "Terminals" }, { "name": "Transactions" }, { "name": "Airtime and Data Vending" }, { "name": "Electricity Vending" }, { "name": "CableTV Subscription" }, { "name": "Betting Vending" } ], "paths": { "/v1/auth/token/issue": { "post": { "description": "You can use this endpoint to authenticate with Nomba.", "operationId": "Obtain access token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueTokenRequest" } } }, "description": "The request payload required for authentication", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/IssueTokenResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "Your authentication request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "summary": "Obtain access token", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Authenticate" ] } }, "/v1/auth/token/refresh": { "post": { "description": "You can use this endpoint to refresh an expired `access_token`.", "operationId": "Refresh an expired token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } }, "description": "The request payload required to refresh the client's `access_token`", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/IssueTokenResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "Your request to refresh a token was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Refresh an expired token", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Authenticate" ] } }, "/v1/auth/token/revoke": { "post": { "description": "You can use this endpoint to revoke an `access_token`.", "operationId": "Revoke an access_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeTokenRequest" } } }, "description": "The request payload required to revoke a clients `access_token`", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeTokenResponse" } } }, "description": "Your request to revoke an access_token was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "summary": "Revoke an access_token", "tags": [ "Authenticate" ] } }, "/v1/accounts": { "get": { "description": "You can use this endpoints to fetch all the accounts tied to a business. Accounts are sorted by date, with the most recently-created account appearing first.", "operationId": "List all accounts", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" } }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "description": "Contains all accounts tied to a specific merchant/business", "items": { "type": "object", "description": "A structure representing a Nomba account.", "properties": { "accountId": { "type": "string", "description": "The id of the account.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "maxLength": 36, "minLength": 36 }, "accountHolderId": { "type": "string", "description": "The businessId of the parent that houses this account.", "example": "412316" }, "accountRef": { "type": "string", "description": "Unique reference used to track an account from an external process. Would be auto-generated if not provided at the point of creation.", "example": "ACT_AMF0YN8UWH8CR8JZ", "maxLength": 20, "minLength": 20 }, "phoneNumber": { "type": "string", "description": "The phoneNumber that is unique to the account bearer.", "example": "2348188667580" }, "email": { "type": "string", "description": "Email of the account bearer.", "example": "test123@exam.ple" }, "bvn": { "type": "string", "description": "Bank verification number of the account bearer.", "example": "12234412345", "maxLength": 11, "minLength": 11 }, "type": { "type": "string", "description": "Type of the account.", "enum": [ "virtual", "physical" ], "example": "physical" }, "accountName": { "type": "string", "description": "Name of the account bearer.", "example": "Testing Testing123", "maxLength": 255, "minLength": 2 }, "banks": { "type": "array", "description": "Contains all the bank details tied to a Nomba account", "items": { "type": "object", "description": "A structure representing a bank account", "properties": { "bankAccountNumber": { "type": "string", "description": "The bank account number tied to the Nomba account.", "example": "0554772814", "maxLength": 10, "minLength": 10 }, "bankName": { "type": "string", "description": "The bank's name.", "example": "Wema Bank" }, "bankAccountName": { "type": "string", "description": "The name on the account.", "example": "M.A Animashaun" } } } }, "address": { "type": "string", "description": "Address of the account bearer.", "example": "4, Alagomeji, Yaba, Lagos", "maxLength": 255, "minLength": 0 }, "status": { "type": "string", "description": "Status of the account.", "enum": [ "active", "pnd", "fraudulent", "suspend" ], "example": "active" }, "currency": { "type": "string", "description": "Primary currency on the account (Only supported at the moment is \u201cNGN\u201d).", "enum": [ "NGN" ], "example": "NGN", "maxLength": 3, "minLength": 3 }, "description": { "type": "string", "description": "Brief description of the account.", "example": "Meat kebab spot" }, "createdAt": { "type": "string", "description": "The date and time this entity was created. This value uses Coordinated Universal Time (UTC) and ISO 8601 format \u2013 `YYYY-MM-DDThh:mm:ssZ`.", "example": "2022-07-08T14:33:00Z" }, "updatedAt": { "type": "string", "description": "The date and time this entity was updated. This value uses Coordinated Universal Time (UTC) and ISO 8601 format \u2013 `YYYY-MM-DDThh:mm:ssZ`.", "example": "2022-07-08T14:33:00Z" } } } }, "cursor": { "type": "string", "format": "int32", "description": "Value used to scroll to next page. It will be empty if there is no more page to scroll to", "example": "xchbaVFsjdsbaADddd" } } } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "List all sub accounts", "tags": [ "Accounts" ] }, "post": { "description": "You can use this endpoint to create a sub account that is part of your business.", "operationId": "Create a sub account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" } } }, "description": "The request payload required to create an account", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CreateAccountResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "Account creation successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Accounts" ] } }, "/v1/accounts/sub-account-details": { "get": { "description": "You can use this endpoint to get details of a sub account.", "operationId": "Fetch account details", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The id of the sub account whose details is to be fetched", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "query", "name": "accountId", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "description": "The unique reference you passed when creating the sub account", "example": "my_unique_reference", "in": "query", "name": "accountRef", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/AccountDetailsResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch sub account details", "tags": [ "Accounts" ] } }, "/v1/accounts/parent": { "get": { "description": "You can use this endpoint to get details of the parent account.", "operationId": "Fetch parent account details", "parameters": [ { "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/AccountDetailsResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch parent account details", "tags": [ "Accounts" ] } }, "/v1/accounts/{subAccountId}/balance": { "get": { "description": "You can use this endpoint to get the balance of a sub account", "operationId": "Fetch account balance", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub account whose balance is to be fetched.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/AccountBalanceResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch sub account balance", "tags": [ "Accounts" ] } }, "/v1/accounts/balance": { "get": { "description": "You can use this endpoint to get the balance of the parent account.", "operationId": "Fetch parent account balance", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/AccountBalanceResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch parent account balance", "tags": [ "Accounts" ] } }, "/v1/accounts/suspend/{subAccountId}": { "put": { "description": "You can use this endpoint to suspend a sub account.", "operationId": "Suspend an account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The id of the account to be suspended.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "type": "boolean", "description": "Response data", "example": true } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Suspend a sub account", "tags": [ "Accounts" ] } }, "/v1/accounts/reactivate/{subAccountId}": { "put": { "description": "You can use this endpoint to reactivate a sub account", "operationId": "Reactivate a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The account to be reactivated.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "type": "boolean", "description": "Response data", "example": true } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Reactivate a sub account", "tags": [ "Accounts" ] } }, "/v1/accounts/{subAccountId}/terminals": { "get": { "description": "You can use this endpoint to fetch terminals linked to a sub account", "operationId": "Fetch terminals assigned to an account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The id of the account whose transactions are to be fetched.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "Terminal ID", "example": "2KUD1234", "in": "query", "name": "terminalId", "schema": { "type": "string" }, "required": false }, { "description": "Terminal ID", "example": "91235335668790", "in": "query", "name": "serialNumber", "schema": { "type": "string" }, "required": false }, { "description": "Terminal Label", "example": "M.A.Terminal", "in": "query", "name": "terminalLabel", "schema": { "type": "string" }, "required": false }, { "description": "Merchant Name", "example": "Daniel.Sc", "in": "query", "name": "merchantName", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TerminalListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch terminals assigned to a sub account", "tags": [ "Accounts" ] } }, "/v1/accounts/terminals": { "get": { "description": "You can use this endpoint to fetch terminals linked to the parent account.", "operationId": "Fetch terminals assigned to the parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "Terminal ID", "example": "2KUD1234", "in": "query", "name": "terminalId", "schema": { "type": "string" }, "required": false }, { "description": "Terminal ID", "example": "91235335668790", "in": "query", "name": "serialNumber", "schema": { "type": "string" }, "required": false }, { "description": "Terminal Label", "example": "M.A.Terminal", "in": "query", "name": "terminalLabel", "schema": { "type": "string" }, "required": false }, { "description": "Merchant Name", "example": "Daniel.Sc", "in": "query", "name": "merchantName", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TerminalListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch terminals assigned to the parent account", "tags": [ "Accounts" ] } }, "/v1/accounts/{accountId}/terminals": { "get": { "description": "You can use this endpoint to fetch terminals linked to a sub account.", "operationId": "Fetch terminals assigned to a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId of the business.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0f", "in": "path", "name": "accountId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "Terminal ID", "example": "2KUD1234", "in": "query", "name": "terminalId", "schema": { "type": "string" }, "required": false }, { "description": "Terminal ID", "example": "91235335668790", "in": "query", "name": "serialNumber", "schema": { "type": "string" }, "required": false }, { "description": "Terminal Label", "example": "M.A.Terminal", "in": "query", "name": "terminalLabel", "schema": { "type": "string" }, "required": false }, { "description": "Merchant Name", "example": "Daniel. Sc", "in": "query", "name": "merchantName", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TerminalListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch terminals assigned to a sub account", "tags": [ "Accounts" ] } }, "/v1/accounts/{subAccountId}/access": { "put": { "description": "You can use this endpoint to update the access of an api client within an account.", "operationId": "Update access to account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The account, where client access is to be updated.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAccessRequest" } } }, "description": "The request payload required to update access to account", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/GenericObjectResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Update access to account", "tags": [ "Accounts" ] } }, "/v1/accounts/virtual": { "post": { "description": "You can use this endpoint to create a virtual account to receive payments.", "operationId": "Create virtual account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVirtualAccountRequest" } } }, "description": "The request payload required to create an account", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CreateVirtualAccountResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "Virtual account creation successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Create virtual account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Virtual Accounts" ] } }, "/v1/accounts/virtual/{subAccountId}": { "post": { "description": "You can use this endpoint to create a virtual account to receive payments for a sub account. Funds sent to the virtual account is collected in the sub account specified", "operationId": "Create virtual account for a sub Account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVirtualAccountRequest" } } }, "description": "The request payload required to create a virtual account", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CreateVirtualAccountResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "Virtual account creation successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Create virtual account for a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId of the business.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0e", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } } ], "tags": [ "Virtual Accounts" ] } }, "/v1/accounts/virtual/list": { "post": { "description": "You can use this endpoint to filter your virtual accounts.", "operationId": "Filter virtual accounts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterVirtualAccountRequest" } } }, "description": "The request payload required to filter virtual accounts.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/VirtualAccountListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Filter virtual accounts", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false } ], "tags": [ "Virtual Accounts" ] } }, "/v1/accounts/virtual/{identifier}": { "put": { "description": "You can use this endpoint to update a virtual account.", "operationId": "Update a virtual account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVirtualAccountRequest" } } }, "description": "The request payload required to update a virtual account. \n Please note that it might take a few seconds for the update to reflect in other banks depending on the bank's notification system.", "required": true }, "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The account reference or 10 digit Virtual account number of the VA to be updated.", "example": "INVOICE-20230823-0000 or 0107841806", "in": "path", "name": "identifier", "required": true, "schema": { "type": "string", "example": "INVOICE-20230823-0000 or 0107841806" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/UpdateVirtualAccountResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a virtual account", "tags": [ "Virtual Accounts" ] }, "get": { "description": "You can use this endpoint to fetch a virtual account.", "operationId": "Fetch a virtual account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The account reference or virtual account number of the virtual account to be fetched.", "example": "3UixJxjfeEZacxYbiNNAJa5R4e9DR", "in": "path", "name": "identifier", "required": true, "schema": { "type": "string", "example": "3UixJxjfeEZacxYbiNNAJa5R4e9DR" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/VirtualAccountObject" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch a virtual account", "tags": [ "Virtual Accounts" ] }, "delete": { "description": "You can use this endpoint to expire a virtual account.", "operationId": "Expire a virtual account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The account reference of the virtual account to be expired.", "example": "3UixJxjfeEZacxYbiNNAJa5R4e9DR", "in": "path", "name": "identifier", "required": true, "schema": { "type": "string", "example": "3UixJxjfeEZacxYbiNNAJa5R4e9DR" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/ExpireVirtualAccountResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Expire a virtual account", "tags": [ "Virtual Accounts" ] } }, "/v1/checkout/order": { "post": { "description": "You can use this endpoint to create an online checkout order. Load the URL returned in 'checkoutLink' property in a browser to allow your customer initiate payment.", "operationId": "Create an online checkout order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } }, "description": "The request payload required to create a checkout order.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "checkout order created successful" }, "data": { "$ref": "#/components/schemas/CreateOrderResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Create an online checkout order", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Online Checkout" ] } }, "/v1/checkout/tokenized-card-payment": { "post": { "description": "You can use this endpoint to charge a customer's card using the tokenized card details.", "operationId": "charge customer with tokenized card data", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizedCardPaymentRequest" } } }, "description": "The request payload required to perform a tokenized payment.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "payment successful" }, "data": { "$ref": "#/components/schemas/TokenizedCardPaymentResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Charge a customer using tokenized card data", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Online Checkout" ] } }, "/v1/checkout/tokenized-card-data": { "get": { "description": "Fetch list of merchant's tokenized cards", "operationId": "List all tokenized cards for merchant", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "Merchant's email address", "example": "abcde@gmail.com", "in": "query", "name": "customerEmail", "schema": { "type": "string" } }, { "description": "Start date, based on the date the token was created", "example": "2023-08-08T23:59:59", "in": "query", "name": "startDate", "schema": { "type": "string" } }, { "description": "end date, based on the date the token was created", "example": "2023-08-08T23:59:59", "in": "query", "name": "endDate", "schema": { "type": "string" } }, { "description": "Specifies the page number to start retriving data from. For first request, this can be ommited or set to 0", "example": 0, "in": "query", "name": "page", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "response description" }, "data": { "type": "object", "properties": { "nextPage": { "type": "string", "format": "int32", "description": "The value of the next page for data retrieval. This value is zero if there are no more pages to retrieve", "example": "2" }, "tokenizedCardDataList": { "type": "array", "description": "Contains all tokenized card data meeting the search criteria", "items": { "$ref": "#/components/schemas/TokenizedCardData" } } } } } } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "List tokenized cards", "tags": [ "Online Checkout" ] }, "post": { "description": "Update a tokenized card details", "operationId": "Update tokenized card data", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTokenizedCardDataRequest" } } }, "description": "The request payload required to update the tokenized card data", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/UpdateTokenizedCardDataResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "Data update successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Update tokenized card data", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Online Checkout" ] }, "delete": { "description": "Delete a tokenized card details", "operationId": "Delete tokenized card data", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTokenizedCardDataRequest" } } }, "description": "The request payload required to update the tokenized card data", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/DeleteTokenizedCardDataResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "Data update successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete tokenized card data", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Online Checkout" ] } }, "/v1/checkout/transaction": { "get": { "description": "Fetch checkout transaction", "operationId": "Fetch a checkout transaction", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "Checkout id type to use for this query. Valid values are the 'ORDER_REFERENCE', to use Order reference passed in when generating the checkout link, and 'ORDER_ID' to use the uuid value returned in the checkout link path.", "example": "ORDER_ID", "in": "query", "name": "idType", "schema": { "type": "string", "enum": [ "ORDER_ID", "ORDER_REFERENCE" ] } }, { "description": "Checkout transaction id based on the value selected in the idType parameter", "example": "120022e-e6ca27-33ed-ee7872e6ca27", "in": "query", "name": "id", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "response description" }, "data": { "$ref": "#/components/schemas/CheckoutTransaction" } } } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch checkout transaction", "tags": [ "Online Checkout" ] } }, "/v1/checkout/refund": { "post": { "description": "You can use this endpoint to refund a checkout transaction.", "operationId": "Refund checkout transaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundCheckoutTransactionRequestDTO" } } }, "description": "The request payload required to refund a checkout transaction.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Refund successful" }, "data": { "$ref": "#/components/schemas/CheckoutDataResponseDTO" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Refund checkout transaction", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Online Checkout" ] } }, "/v1/checkout/order/{orderReference}": { "get": { "description": "Use this endpoint to fetch a single checkout order, using the order reference that was returned when the Order was created", "operationId": "Fetch Checkout order details", "parameters": [ { "description": "Order reference", "example": "693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea", "in": "path", "name": "orderReference", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/GetOrderDetails" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Get Order details based on the generated Order reference", "tags": [ "Charge" ] } }, "/v1/checkout/checkout-card-detail": { "post": { "description": "Use this endpoint to submit the customers card details", "operationId": "Submit customer card details", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitCardDetails" } } }, "description": "The request payload required to filter account transactions.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/SubmitCardDetailsResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit customer card details", "tags": [ "Charge" ] } }, "/v1/checkout/checkout-card-otp": { "post": { "description": "Use this endpoint to submit the payment OTP sent to the customer's phones from the payment gateway", "operationId": "Submit customer payment OTP", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitCardOTP" } } }, "description": "The request payload required to authenticate the Card payment", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/SubmitCardOTPResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit customer card OTP", "tags": [ "Charge" ] } }, "/v1/checkout/resend-otp": { "post": { "description": "Use this endpoint to resend the payment OTP to the customer's phone", "operationId": "Resend customer payment OTP", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDataRequest" } } }, "description": "The request payload required to resend the Card payment", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CheckoutDataResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Resend OTP to customer's phone", "tags": [ "Charge" ] } }, "/v1/checkout/confirm-transaction-receipt": { "post": { "description": "Use this endpoint to fetch the checkout transaction details and get the status of the transaction after OTP is submitted or transfer is made", "operationId": "Fetch Checkout transaction details", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDataRequest" } } }, "description": "Fetch checkout transaction details", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CheckoutTransactionDetailsResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch checkout transaction details", "tags": [ "Charge" ] } }, "/v1/checkout/get-checkout-kta/{orderReference}": { "get": { "description": "Use this endpoint to Get a flash account number which the customer can use to make a transfer payment.", "operationId": "Fetch Checkout flash account number", "parameters": [ { "description": "Order reference", "example": "693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea", "in": "path", "name": "orderReference", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CheckoutAccountNumberResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch checkout Flash account number for transfer payment", "tags": [ "Charge" ] } }, "/v1/checkout/user-card/auth": { "post": { "description": "Use this endpoint to request an OTP to be sent to be sent to the users phone number to authenticate the user before saving the card. This endpoint is called after payment is successful, and the user requested to save their card for later.", "operationId": "Request user OTP to authenticate user ", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAuthenticateUserRequest" } } }, "description": "Request OTP before saving a user's card", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CheckoutDataResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Request OTP before saving a user's card", "tags": [ "Charge" ] } }, "/v1/checkout/user-card/saved-card/auth": { "post": { "description": "Use this endpoint to request an OTP to be sent to a user's phone number to authenticate before retrieving the saved cards mapped to the user's email. Use this endpoint when the Order details endpoint indicates the user already has saved cards.", "operationId": "Request user OTP to authenticate user who already has saved cards ", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDataRequest" } } }, "description": "Request OTP to validate a user before fetching saved cards", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CheckoutDataResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Request OTP to validate a user before fetching saved cards", "tags": [ "Charge" ] } }, "/v1/checkout/user-card": { "post": { "description": "Use this endpoint to submit the user OTP send to the user's mobile number. This will result in the user's card being saved for later use.", "operationId": "Submit User OTP", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSubmitUserOTPRequest" } } }, "description": "Submit User OTP", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CheckoutDataResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit user OTP", "tags": [ "Charge" ] } }, "/v1/checkout/user-card/{orderReference}": { "get": { "description": "Use this endpoint to Get a user's saved cards. Requires user OTP send to the user after calling /checkout/user-card/saved-card/auth", "operationId": "Fetch User saved cards", "parameters": [ { "description": "Order referene", "example": "693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea", "in": "path", "name": "orderReference", "required": true, "schema": { "type": "string" } }, { "description": "otp sent to the user's mobile number", "example": "1234", "in": "query", "name": "otp", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TokenizedCardDataList" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Get user saved cards", "tags": [ "Charge" ] } }, "/v1/checkout/transaction/cancel": { "post": { "description": "Use this endpoint to Cancel an incomplete checkout transaction", "operationId": "Cancel checkout transaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCancelTransactionRequest" } } }, "description": "Submit User OTP", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CheckoutDataResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel Checkout transaction", "tags": [ "Charge" ] } }, "/v1/transfers/banks": { "get": { "description": "You can use this endpoint to fetch all banks, their names and codes.", "operationId": "Fetch bank codes and names", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/BanksListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch bank codes and names", "tags": [ "Transfers" ] } }, "/v1/transfers/bank/lookup": { "post": { "description": "You can use this endpoint to perform bank account lookup.", "operationId": "Perform bank account lookup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountLookupRequest" } } }, "description": "The request payload required to perform bank account lookup", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/BankAccountLookupResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Perform bank account lookup", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Transfers" ] } }, "/v2/transfers/bank": { "post": { "description": "You can use this endpoint to perform bank account transfer.", "operationId": "Perform bank account transfer from the parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountTransferRequest" } } }, "description": "The request payload required to perform bank account transfer.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "200", "description": "Response Code" }, "description": { "type": "string", "example": "SUCCESS", "enum": [ "SUCCESS", "PROCESSING", "FAILED", "BAD_REQUEST", "INSUFFICIENT_BALANCE", "ACCOUNT_NOT_FOUND", "INVALID_TRANSACTION", "WALLET_NOT_FOUND", "BLACKLISTED" ], "description": "Response description" }, "message": { "type": "string", "example": "Success", "description": "Returned response message" }, "status": { "type": "boolean", "example": "true", "description": "Response status" }, "data": { "$ref": "#/components/schemas/BankAccountTransferResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "201": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "201" }, "description": { "type": "string", "example": "PROCESSING" }, "message": { "type": "string", "example": "Unable to process response, please rely on web hook" }, "status": { "type": "boolean", "example": false }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "PENDING_BILLING" } } } } } } }, "description": "Transfer is being processed \u2014 the final status will be delivered via webhook. Mark the transaction as pending and do not retry with a new reference." } }, "security": [ { "BearerAuth": [] } ], "summary": "Perform bank account transfer from the parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Transfers" ] } }, "/v2/transfers/bank/{subAccountId}": { "post": { "description": "You can use this endpoint to perform bank account transfer using a sub account. \n To use this, please reach out to us to profile you for sub account transfer.", "operationId": "Perform bank account transfer from account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountTransferRequest" } } }, "description": "The request payload required to perform bank account transfer.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/BankAccountTransferResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "201": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "201" }, "description": { "type": "string", "example": "PROCESSING" }, "message": { "type": "string", "example": "Unable to process response, please rely on web hook" }, "status": { "type": "boolean", "example": false }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "PENDING_BILLING" } } } } } } }, "description": "Transfer is being processed \u2014 the final status will be delivered via webhook. Mark the transaction as pending and do not retry with a new reference." } }, "security": [ { "BearerAuth": [] } ], "summary": "Perform bank account transfer from the sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId to transfer from.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } } ], "tags": [ "Transfers" ] } }, "/v2/transfers/wallet": { "post": { "description": "You can use this endpoint to perform a wallet transfer.", "operationId": "Perform wallet transfer from the parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransferRequest" } } }, "description": "The request payload required to perform a wallet transfer.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/WalletTransferResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "201": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "201" }, "description": { "type": "string", "example": "PROCESSING" }, "message": { "type": "string", "example": "Unable to process response, please rely on web hook" }, "status": { "type": "boolean", "example": false }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "PENDING_BILLING" } } } } } } }, "description": "Transfer is being processed \u2014 the final status will be delivered via webhook. Mark the transaction as pending and do not retry with a new reference." } }, "security": [ { "BearerAuth": [] } ], "summary": "Perform wallet transfer from the parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Transfers" ] } }, "/v2/transfers/wallet/{subAccountId}": { "post": { "description": "You can use this endpoint to perform a wallet transfer from a sub account", "operationId": "Perform wallet transfer from a sub account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransferRequest" } } }, "description": "The request payload required to perform a wallet transfer.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/WalletTransferResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "201": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "201" }, "description": { "type": "string", "example": "PROCESSING" }, "message": { "type": "string", "example": "Unable to process response, please rely on web hook" }, "status": { "type": "boolean", "example": false }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "PENDING_BILLING" } } } } } } }, "description": "Transfer is being processed \u2014 the final status will be delivered via webhook. Mark the transaction as pending and do not retry with a new reference." } }, "security": [ { "BearerAuth": [] } ], "summary": "Perform wallet transfer from a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The accountId to transfer from.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } } ], "tags": [ "Transfers" ] } }, "/v1/terminals/assign/{subAccountId}": { "post": { "description": "You can use this endpoint to assign a terminal to an sub account.", "operationId": "Assign a terminal to an account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalAssignmentRequest" } } }, "description": "The request payload required to assign a terminal to an account.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TerminalResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Assign a terminal to a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId whose terminals are to be fetched.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } } ], "tags": [ "Terminals" ] } }, "/v1/terminals/assign": { "post": { "description": "You can use this endpoint to assign a terminal to the parent account.", "operationId": "Assign a terminal to the parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalAssignmentRequest" } } }, "description": "The request payload required to assign a terminal to an account.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TerminalResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Assign a terminal to the parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Terminals" ] } }, "/v1/terminals/unassign/{subAccountId}": { "post": { "description": "You can use this endpoint to un-assign a terminal from a sub account.", "operationId": "Un-assign terminal from an account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalAssignmentRequest" } } }, "description": "The request payload required to un-assign a terminal from a sub account", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TerminalResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Un-assign terminal from a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId of the business.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } } ], "tags": [ "Terminals" ] } }, "/v1/terminals/unassign": { "post": { "description": "You can use this endpoint to un-assign a terminal from the parent account.", "operationId": "Un-assign a terminal from the parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalAssignmentRequest" } } }, "description": "The request payload required to un-assign a terminal from an account", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TerminalResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Un-assign a terminal from the parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Terminals" ] } }, "/v1/terminals/payment-request/{terminalId}": { "post": { "description": "You can use this endpoint to trigger a payment request on a nomba terminal", "operationId": "Send payment request to terminal", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalPaymentRequest" } } }, "description": "The request payload required to send payment request to a nomba terminal", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TerminalPaymentResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Send payment request to terminal", "tags": [ "Terminals" ] } }, "/v1/transactions/bank/{subAccountId}": { "get": { "description": "You can use this endpoint to fetch credit/debit transactions on a sub account.", "operationId": "Fetch credit/debit transactions on a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId of the business.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "This starting date (UTC). Sample date: `2023-01-01T00:00:00`", "in": "query", "name": "dateFrom", "example": "2023-09-08T00:00:00.007Z", "schema": { "type": "string" }, "required": false }, { "description": "This ending date (UTC). Sample date: `2024-09-30T23:59:59`", "in": "query", "name": "dateTo", "example": "2023-08-08T23:59:59.007Z", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/BankTransactionListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch credit/debit transactions on a sub account", "tags": [ "Transactions" ] } }, "/v1/transactions/bank": { "get": { "description": "You can use this endpoint to fetch credit/debit transactions on the parent account.", "operationId": "Fetch credit/debit transactions on the parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "This starting date (UTC). Sample date: `2023-01-01T00:00:00`", "in": "query", "name": "dateFrom", "example": "2023-09-08T00:00:00.007Z", "schema": { "type": "string" }, "required": false }, { "description": "This ending date (UTC). Sample date: `2024-09-30T23:59:59`", "in": "query", "name": "dateTo", "example": "2023-08-08T23:59:59.007Z", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/BankTransactionListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch credit/debit transactions on the parent account", "tags": [ "Transactions" ] } }, "/v1/transactions/accounts/{subAccountId}": { "get": { "description": "You can use this endpoint to fetch transactions on a sub account.", "operationId": "Fetch transactions on a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId of the business.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "This starting date (UTC). Sample date: `2023-01-01T00:00:00`", "in": "query", "name": "dateFrom", "example": "2023-09-08T00:00:00.007Z", "schema": { "type": "string" }, "required": false }, { "description": "This ending date (UTC). Sample date: `2024-09-30T23:59:59`", "in": "query", "name": "dateTo", "example": "2023-08-08T23:59:59.007Z", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TransactionListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch transactions on a sub account", "tags": [ "Transactions" ] }, "post": { "description": "You can use this endpoint to filter transactions on a sub account.", "operationId": "Filter sub account transactions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterTransactionRequest" } } }, "description": "The request payload required to filter account transactions.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TransactionListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Filter sub account transactions", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId of the business.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0e", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "This starting date (UTC). Sample date: `2023-01-01T00:00:00`", "in": "query", "name": "dateFrom", "example": "2023-09-08T00:00:00.007Z", "schema": { "type": "string" }, "required": false }, { "description": "This ending date (UTC). Sample date: `2024-09-30T23:59:59`", "in": "query", "name": "dateTo", "example": "2023-08-08T23:59:59.007Z", "schema": { "type": "string" }, "required": false } ], "tags": [ "Transactions" ] } }, "/v1/transactions/accounts": { "get": { "description": "You can use this endpoint to fetch transactions on the parent account.", "operationId": "Fetch transactions on the parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "This starting date (UTC). Sample date: `2023-01-01T00:00:00`", "in": "query", "name": "dateFrom", "example": "2023-09-08T00:00:00.007Z", "schema": { "type": "string" }, "required": false }, { "description": "This ending date (UTC). Sample date: `2024-09-30T23:59:59`", "in": "query", "name": "dateTo", "example": "2023-08-08T23:59:59.007Z", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TransactionListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch transactions on the parent account", "tags": [ "Transactions" ] }, "post": { "description": "You can use this endpoint to filter transactions on the parent account.", "operationId": "Filter parent account transactions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterTransactionRequest" } } }, "description": "The request payload required to filter account transactions.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TransactionListResults" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Filter parent account transactions", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "This endpoint is paginated. `limit` describes the size of the page you are querying", "example": 10, "in": "query", "name": "limit", "schema": { "type": "integer", "format": "int32" }, "required": false }, { "description": "The `cursor` is used to scroll to the next page. When making the first call to list all accounts, there is no need to pass in any cursor since the API has not returned any cursor back to you. Only use cursor when the API provides it", "example": "xchbaVFsjdsbaADddd", "in": "query", "name": "cursor", "schema": { "type": "string" }, "required": false }, { "description": "This starting date (UTC). Sample date: `2023-01-01T00:00:00`", "in": "query", "name": "dateFrom", "example": "2023-09-08T00:00:00.007Z", "schema": { "type": "string" }, "required": false }, { "description": "This ending date (UTC). Sample date: `2024-09-30T23:59:59`", "in": "query", "name": "dateTo", "example": "2023-08-08T23:59:59.007Z", "schema": { "type": "string" }, "required": false } ], "tags": [ "Transactions" ] } }, "/v1/transactions/accounts/{subAccountId}/single": { "get": { "description": "You can use this endpoint to fetch a single transaction on a sub account", "operationId": "Fetch a single transaction on a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId whose transactions are to be fetched.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } }, { "description": "Transaction ID/Reference", "example": "POS-WITHDRAW-DFC05-693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea", "in": "query", "name": "transactionRef", "required": false, "schema": { "type": "string" } }, { "description": "Merchant transaction reference", "example": "c90d-4b25-ad0f", "in": "query", "name": "merchantTxRef", "required": false, "schema": { "type": "string" } }, { "description": "Online checkout order reference", "example": "693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea", "in": "query", "name": "orderReference", "required": false, "schema": { "type": "string" } }, { "description": "Online checkout order id", "example": "285e4ad2-665f-453b-8795-e854cab5757b", "in": "query", "name": "orderId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TransactionResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch a single transaction on a sub account", "tags": [ "Transactions" ] } }, "/v1/transactions/accounts/single": { "get": { "description": "You can use this endpoint to fetch a single transaction on the parent account.", "operationId": "Fetch a single transaction on the parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "Transaction ID/Reference", "example": "POS-WITHDRAW-DFC05-693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea", "in": "query", "name": "transactionRef", "required": false, "schema": { "type": "string" } }, { "description": "Merchant transaction reference", "example": "c90d-4b25-ad0f", "in": "query", "name": "merchantTxRef", "required": false, "schema": { "type": "string" } }, { "description": "Online checkout order reference", "example": "693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea", "in": "query", "name": "orderReference", "required": false, "schema": { "type": "string" } }, { "description": "Online checkout order id", "example": "285e4ad2-665f-453b-8795-e854cab5757b", "in": "query", "name": "orderId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TransactionResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch a single transaction on the parent account", "tags": [ "Transactions" ] } }, "/v1/transactions/requery/{sessionId}": { "get": { "description": "This endpoint is for fetching (requerying) a transaction status.", "operationId": "Confirm a transaction's status by sessionId", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "SessionId", "example": "000032891359184717316165338085", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/TransactionResult" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Confirm a transaction's status by sessionId", "tags": [ "Transactions" ] } }, "/v1/bill/data-plan/{telco}": { "get": { "description": "You can use this endpoint to fetch data plans available on a telco (network provider)", "operationId": "Fetch data plans available on a telco (network provider)", "parameters": [ { "description": "Network provider", "example": "glo", "in": "path", "name": "telco", "required": true, "schema": { "type": "string" } }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/DataPlanList" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch data plans available on a telco (network provider)", "tags": [ "Airtime and Data Vending" ] } }, "/v1/bill/topup": { "post": { "description": "You can use this endpoint to make airtime purchases via parent account", "operationId": "Make airtime purchases via parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirtimePurchaseRequest" } } }, "description": "The request payload required to make airtime purchases", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/AirtimePurchaseResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Make airtime purchases via parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Airtime and Data Vending" ] } }, "/v1/bill/topup/{subAccountId}": { "post": { "description": "You can use this endpoint to make airtime purchases via a sub account", "operationId": "Make airtime purchases via specific or sub account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirtimePurchaseRequest" } } }, "description": "The request payload required to make airtime purchases", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/AirtimePurchaseResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Make airtime purchases via a sub account", "parameters": [ { "description": "The parent accountId of the business this sub account belongs to", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId via which airtime is to be purchased", "in": "path", "name": "subAccountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Airtime and Data Vending" ] } }, "/v1/bill/data": { "post": { "description": "You can use this endpoint to vend data via parent account", "operationId": "Vend data bundles via parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataVendingRequest" } } }, "description": "The request payload required to vend data bundles", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/DataVendingResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Vend data bundles via parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Airtime and Data Vending" ] } }, "/v1/bill/data/{subAccountId}": { "post": { "description": "You can use this endpoint to vend data via a sub account", "operationId": "Vend data bundles via specific or sub account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataVendingRequest" } } }, "description": "The request payload required to vend data bundles", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/DataVendingResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Vend data bundles via a sub account", "parameters": [ { "description": "The parent accountId of the business this sub account belongs to", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The sub accountId via which data bundle is to be vended", "in": "path", "name": "subAccountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Airtime and Data Vending" ] } }, "/v1/bill/cabletv/lookup": { "get": { "description": "This endpoint is for fetching customer information data", "operationId": "CABLETV_LOOKUP", "parameters": [ { "description": "customerId", "example": "dstv12233", "in": "query", "name": "customerId", "schema": { "type": "string" } }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "cableTvType", "example": "dstv", "in": "query", "name": "cableTvType", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "type": "string", "example": "John Doe", "description": "The name of the customer" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch customer information from a cable tv provider", "tags": [ "CableTV Subscription" ] } }, "/v1/bill/cabletv": { "post": { "description": "You can use this endpoint to make cable tv subscription via parent account", "operationId": "Cable Tv subscription via parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CableTvSubscriptionRequest" } } }, "description": "The request payload required for a cable tv subscription", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CableTvSubscriptionResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "CableTv subscription via parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "CableTV Subscription" ] } }, "/v1/bill/cabletv/{subAccountId}": { "post": { "description": "You can use this endpoint to make cable tv subscription via a sub account", "operationId": "Cable Tv subscription via a sub account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CableTvSubscriptionRequest" } } }, "description": "The request payload required for a cable tv subscription", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CableTvSubscriptionResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "CableTv subscription via a sub account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The identifier for the account through which this transaction is to be carried out.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } } ], "tags": [ "CableTV Subscription" ] } }, "/v1/bill/electricity/discos": { "get": { "description": "You can use this endpoint to fetch electricity providers/discos", "operationId": "Fetch electricity providers", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/DiscoList" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch discos/electricity providers", "tags": [ "Electricity Vending" ] } }, "/v1/bill/electricity/lookup": { "get": { "description": "This endpoint is for fetching customer information data from an electricity vending provider", "operationId": "ELECTRICITY_CUSTOMER_LOOKUP", "parameters": [ { "description": "disco", "example": "phed", "in": "query", "name": "disco", "schema": { "type": "string" } }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "customerId", "example": "12347899", "in": "query", "name": "customerId", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "type": "string", "example": "John Doe", "description": "The name of the customer" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch customer information from an electricity provider", "tags": [ "Electricity Vending" ] } }, "/v1/bill/electricity": { "post": { "description": "You can use this endpoint to vend electricity via parent account", "operationId": "Vend electricity via parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElectricityVendingRequest" } } }, "description": "The request payload required to vend electricity", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/ElectricityVendingResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Vend electricity via parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Electricity Vending" ] } }, "/v1/bill/electricity/{subAccountId}": { "post": { "description": "You can use this endpoint to vend electricity via a sub account", "operationId": "Vend electricity via a sub account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElectricityVendingRequest" } } }, "description": "The request payload required to vend electricity", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/ElectricityVendingResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Vend electricity via a specific account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The identifier for the account through which this transaction is to be carried out.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } } ], "tags": [ "Electricity Vending" ] } }, "/v1/bill/betting/providers": { "get": { "description": "You can use this endpoint to fetch betting providers", "operationId": "Fetch betting providers", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/BettingProvidersList" }, "message": { "type": "string", "example": "SUCCESS", "description": "Response message" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch betting providers", "tags": [ "Betting Vending" ] } }, "/v1/bill/betting/lookup": { "get": { "description": "This endpoint is for fetching customer information data from a bet vending provider", "operationId": "BETTING_CUSTOMER_LOOKUP", "parameters": [ { "description": "providerId", "example": "bet9ja", "in": "query", "name": "providerId", "schema": { "type": "string" } }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "customerId", "example": "12347899", "in": "query", "name": "customerId", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "type": "string", "example": "John Doe", "description": "The name of the customer" }, "message": { "type": "string", "example": "SUCCESS", "description": "Response message" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } }, "security": [ { "BearerAuth": [] } ], "summary": "Fetch customer information from a betting provider", "tags": [ "Betting Vending" ] } }, "/v1/bill/betting": { "post": { "description": "You can use this endpoint to vend betting via parent account", "operationId": "Vend betting via parent account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BettingVendingRequest" } } }, "description": "The request payload required to vend betting", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/BettingVendingResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Vend betting via parent account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "tags": [ "Betting Vending" ] } }, "/v1/bill/betting/{subAccountId}": { "post": { "description": "You can use this endpoint to vend betting via a sub account", "operationId": "Vend betting via a sub account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BettingVendingRequest" } } }, "description": "The request payload required to vend betting", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "Success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/BettingVendingResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ], "summary": "Vend betting via a specific account", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "The identifier for the account through which this transaction is to be carried out.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "in": "path", "name": "subAccountId", "required": true, "schema": { "type": "string" } } ], "tags": [ "Betting Vending" ] } }, "/v1/direct-debits/mandates": { "get": { "tags": [ "Direct Debits" ], "summary": "Get mandates by filters", "parameters": [ { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "format": "uuid", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "example": 0 } }, { "name": "pageSize", "in": "query", "required": true, "schema": { "type": "integer", "example": 20 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of mandates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResult" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/direct-debits/update-status": { "put": { "tags": [ "Direct Debits" ], "summary": "Update mandate status", "description": "Updates the status of a direct debit mandate (e.g., SUSPEND, ACTIVE).", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The vendor account ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMandateStatusRequest" }, "example": { "mandateId": "c93e1e1b-85f5-461e-8b9b-74ee091d4aa4", "status": "SUSPEND" } } } }, "responses": { "200": { "description": "Mandate status updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMandateStatusResponse" }, "example": { "code": "00", "description": "SUCCESS", "data": { "mandateId": "c93e1e1b-85f5-461e-8b9b-74ee091d4aa4", "mandateStatus": "Advise not sent" }, "message": "SUCCESS", "status": true } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } } } }, "/v1/direct-debits/debit-mandate": { "post": { "tags": [ "Direct Debits" ], "summary": "Debit a mandate", "description": "Debits a customer's account using an active mandate.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The vendor account ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitMandateRequest" }, "example": { "mandateId": "89b0efc0-dde5-49e2-8bde-5523ae081c43", "amount": "110.00" } } } }, "responses": { "200": { "description": "Mandate debited successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitMandateResponse" }, "example": { "code": "00", "description": "SUCCESS", "data": { "mandateId": "89b0efc0-dde5-49e2-8bde-5523ae081c43", "status": "SUCCESS", "amount": "110.00", "message": "Approved or completed successfully" }, "message": "SUCCESS", "status": true } } } }, "400": { "description": "Invalid request payload" }, "401": { "description": "Unauthorized - invalid or missing token" } } } }, "/v1/direct-debits/status?mandateId={mandateId}": { "get": { "tags": [ "Direct Debits" ], "summary": "Get Mandate Status", "description": "Fetches the status of a specific mandate by mandateId.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The vendor account ID" }, { "name": "mandateId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the mandate" } ], "responses": { "200": { "description": "Mandate status fetched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMandateStatusResponse" }, "example": { "code": "00", "description": "SUCCESS", "data": { "customerAccountName": "Kolapo Ojo", "mandateId": "c93e1e1b-85f5-461e-8b9b-74ee091d4aa4", "customerAccountNumber": "80793414434", "mandateStatus": "Active", "rejectionComment": "Expired e-mandate", "mandateAdviceStatus": "Advise not sent" }, "message": "SUCCESS", "status": true } } } }, "400": { "description": "Invalid mandateId provided" }, "401": { "description": "Unauthorized - invalid or missing token" } } } }, "/v1/direct-debits/{mandateId}": { "get": { "tags": [ "Direct Debits" ], "summary": "Get Mandate by ID", "description": "Fetches full details of a specific direct debit mandate using its mandateId.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The vendor account ID" }, { "name": "mandateId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the mandate" } ], "responses": { "200": { "description": "Mandate details fetched successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMandateByIdResponse" }, "example": { "code": "00", "description": "SUCCESS", "data": { "status": "ACTIVE", "customerAccountNumber": "8033234423", "customerAccountName": "Kolapo Adeoti", "bankCode": "057", "amount": 100.0, "customerName": "Kolapo Adeoti", "customerAddress": "maryland Ikeja computer village", "customerEmail": "kolapoadeoti@gmail.com", "customerPhoneNumber": "08033234423", "merchantReference": "120033124001", "frequency": "VARIABLE", "startDate": [ 2025, 8, 13, 15, 30 ], "endDate": [ 2025, 8, 30, 10, 40 ], "mandateAdviceStatus": null, "mandateId": "e50b7835-502c-4cfe-9893-47657633d7a2" }, "message": "SUCCESS", "status": true } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } } } }, "/v1/direct-debits": { "post": { "tags": [ "Direct Debits" ], "summary": "Create a Direct Debit Mandate", "description": "Creates a new direct debit mandate for a customer.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "accountId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The vendor account ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMandateRequest" }, "example": { "customerAccountNumber": "0212343456", "bankCode": "101", "customerName": "Kolapo Ojo", "customerAddress": "maryland Ikeja computer village", "customerAccountName": "Kolapo Ojo", "amount": 100, "frequency": "WEEKLY", "narration": "test e mandate response", "customerPhoneNumber": "08074332234", "merchantReference": "12003074001", "startDate": "2025-08-29T14:58", "endDate": "2025-08-30T10:40", "customerEmail": "kolapo@gmail.com", "startImmediately": true } } } }, "responses": { "200": { "description": "Mandate created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMandateResponse" }, "example": { "responseMessage": "Success", "responseCode": "00", "data": { "mandateId": "e50b7835-502c-4cfe-9893-47657633d7a2", "merchantReference": "12003074001", "phoneNumber": "08073345562", "description": "Welcome to NIBSS e-mandate authentication service, a seamless and convenient authentication experience. Kindly proceed with a token payment of N50.00 into account number 9880218357 with Paystack-Titan Bank. This payment will trigger the authentication of your mandate. Thank You" } } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "Resource not available" } } } }, "/v1/global-payout/transfer/authorize": { "post": { "description": "Initiate and authorize a cross-border transfer. Manages the complete transfer lifecycle from initiation to final authorization. Supports BANK, MobileMoney, INTERAC, FASTER_PAYMENTS, SEPA, ACH, and WIRE payment methods.", "operationId": "Authorize Transfer", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "requestBody": { "required": true, "description": "Transfer authorization payload", "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "sourceCurrency", "destinationCurrency", "receiverName", "sourceCountryIsoCode", "destinationCountryIsoCode", "authCode", "paymentMethod", "accountType" ], "properties": { "amount": { "type": "number", "example": 500.0 }, "sourceCurrency": { "type": "string", "example": "USD" }, "destinationCurrency": { "type": "string", "example": "USD" }, "receiverName": { "type": "string", "example": "John Cena" }, "sourceCountryIsoCode": { "type": "string", "example": "CD" }, "destinationCountryIsoCode": { "type": "string", "example": "CD" }, "authCode": { "type": "string", "format": "password", "example": "2580" }, "paymentMethod": { "type": "string", "enum": [ "BANK", "MobileMoney", "INTERAC", "FASTER_PAYMENTS", "SEPA", "ACH", "WIRE" ], "example": "MobileMoney", "description": "Payment rail. Determines which additional fields are required. Use Fetch Payment Methods with code or name to get method-specific requirements." }, "accountNumber": { "type": "string", "example": "0903086112", "description": "Account number, IBAN, or phone number for MobileMoney. Required for BANK, MobileMoney, FASTER_PAYMENTS, SEPA." }, "institutionCode": { "type": "string", "example": "access_bank", "description": "Routing code. Bank code from /bank/providers for BANK (DRC). Sort code for FASTER_PAYMENTS, SWIFT/BIC for SEPA, institution number for BANK (Canada)." }, "institutionName": { "type": "string", "example": "Mpesa", "description": "Bank or provider display name. Use displayName from List Institution Providers." }, "accountType": { "type": "string", "enum": [ "INDIVIDUAL", "CORPORATE" ], "example": "INDIVIDUAL", "description": "Required account type of the recipient. Select one of the values returned in accountTypes from Fetch Payment Methods. ACH supports only INDIVIDUAL; WIRE supports INDIVIDUAL and CORPORATE." }, "bankAccountType": { "type": "string", "enum": [ "CHECKING", "SAVINGS" ], "example": "CHECKING", "description": "Recipient bank account type. Required for ACH and WIRE. Select one of the values returned in bankAccountTypes from Fetch Payment Methods." }, "purposeOfPayment": { "type": "string", "example": "FAMILY_SUPPORT", "description": "Reason for the transfer. Required for ACH, WIRE, and SEPA. Select one of the values returned in purposeOfPayments from Fetch Payment Methods; do not send arbitrary text." }, "narration": { "type": "string", "example": "Family support" }, "lockedExchangeRateId": { "type": "string", "example": "01k7pcakf0t8g03rvny3z5mr1p", "description": "Optional locked exchange rate ID from Convert Money. Use this when you want to lock the exchange rate and destination amount before authorizing." }, "bankAddress": { "type": "string", "example": "383 Madison Avenue", "description": "Bank street address. Required for United States WIRE." }, "bankCity": { "type": "string", "example": "New York", "description": "Bank city. Required for United States WIRE." }, "bankState": { "type": "string", "example": "NY", "description": "Bank state. Required for United States WIRE." }, "bankZipCode": { "type": "string", "example": "10017", "description": "Bank ZIP code. Required for United States WIRE." }, "beneficiary": { "type": "object", "description": "Required for INTERAC; partially required for BANK (Canada).", "properties": { "beneficiaryEmail": { "type": "string", "example": "jane.doe@email.com" }, "securityQuestion": { "type": "string", "example": "What is your pets name?" }, "securityQuestionAnswer": { "type": "string", "example": "Fluffy" }, "transitNumber": { "type": "string", "description": "Bank transit number (Canada only)." }, "beneficiaryAddress": { "type": "string", "example": "123 Main Street" }, "beneficiaryCity": { "type": "string", "example": "New York" }, "beneficiaryState": { "type": "string", "example": "NY" }, "beneficiaryPostCode": { "type": "string", "example": "10001" } } } } } } } }, "responses": { "200": { "description": "Transfer authorized successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "object", "properties": { "wtTransactionId": { "type": "string", "example": "01kky197w3xc6wyjenpc5r0tnp", "description": "Unique GlobalPayout transaction ID. Use to track via Fetch Transaction." }, "coreTransactionId": { "type": "string", "example": "API-FX_TX_DR-08A1B-6add611a-e538-4e67-bcf9-661c77a16804" }, "status": { "type": "string", "example": "PROCESSING", "enum": [ "PROCESSING", "COMPLETED", "FAILED", "PENDING" ] }, "coreStatus": { "type": "string", "example": "PAYMENT_SUCCESSFUL" }, "type": { "type": "string", "example": "TRANSFER" }, "prettyStatus": { "type": "string", "example": "Successful" }, "meta": { "type": "object", "description": "Transaction metadata including currency details, amounts, and routing info.", "properties": { "source_amount": { "type": "string", "example": "250.0" }, "destination_amount": { "type": "string", "example": "250.0" }, "source_currency": { "type": "string", "example": "USD" }, "destination_currency": { "type": "string", "example": "USD" }, "amount_charged": { "type": "string", "example": "255.0" }, "currency_pair_name": { "type": "string", "example": "USD/USD" }, "payment_method": { "type": "string", "example": "MobileMoney" }, "destination_country": { "type": "string", "example": "CD" }, "destination_country_name": { "type": "string", "example": "Congo DR" }, "source_country": { "type": "string", "example": "CD" }, "narration": { "type": "string", "example": "Family support" }, "trade_side": { "type": "string", "example": "BUY" }, "spread_amount": { "type": "string", "example": "0.0" }, "spread_currency": { "type": "string", "example": "USD" }, "wt_transaction_id": { "type": "string", "example": "01kky197w3xc6wyjenpc5r0tnp" }, "trade_context": { "type": "string", "example": "default" }, "transactionCategory": { "type": "string", "example": "General" }, "payment_destination_type": { "type": "string", "example": "Account" }, "tradeType": { "type": "string", "example": "FIXED_TRADE" } } } } } } } } } } } } }, "/v1/global-payout/exchange/authorize": { "post": { "description": "Transfer funds between your own accounts in different currencies.", "operationId": "Authorize Exchange", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "requestBody": { "required": true, "description": "Exchange authorization payload", "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "sourceCurrency", "destinationCurrency", "senderName", "receiverName", "sourceCountryIsoCode", "destinationCountryIsoCode", "authCode" ], "properties": { "amount": { "type": "number", "example": 1 }, "sourceCurrency": { "type": "string", "example": "USD" }, "destinationCurrency": { "type": "string", "example": "CDF" }, "senderName": { "type": "string", "example": "John Doe" }, "receiverName": { "type": "string", "example": "John Doe" }, "sourceCountryIsoCode": { "type": "string", "example": "CD" }, "destinationCountryIsoCode": { "type": "string", "example": "CD" }, "authCode": { "type": "string", "format": "password", "example": "5555" }, "narration": { "type": "string", "example": "Transfer between my accounts" }, "lockedExchangeRateId": { "type": "string", "example": "01kkk4b7rh8pcvtw1s1nxs144s", "description": "The exchangeRateId from a prior Fetch Exchange Rates call. When provided, the exchange is fulfilled at that exact rate." } } } } } }, "responses": { "200": { "description": "Exchange authorized successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "object", "properties": { "wtTransactionId": { "type": "string", "example": "01kkk8cjk0fpw9jx2n01wd8yfw" }, "coreTransactionId": { "type": "string", "example": "API-P2P-CB9EC-0c2d962e-4730-48e7-b522-d65cac511549" }, "status": { "type": "string", "example": "PROCESSING" }, "coreStatus": { "type": "string", "example": "SUCCESS" }, "type": { "type": "string", "example": "EXCHANGE" } } } } } } } } } } }, "/v1/global-payout/money/convert": { "post": { "description": "Calculate a currency conversion and lock an exchange rate before initiating a transfer.", "operationId": "Convert Money", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "requestBody": { "required": true, "description": "Currency conversion payload", "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency", "destinationCurrency", "transactionType", "sourceCountryIsoCode" ], "properties": { "amount": { "type": "number", "example": 15 }, "currency": { "type": "string", "example": "USD", "description": "ISO 4217 source currency code." }, "destinationCurrency": { "type": "string", "example": "EUR", "description": "ISO 4217 destination currency code." }, "transactionType": { "type": "string", "example": "EXCHANGE" }, "sourceCountryIsoCode": { "type": "string", "example": "NG" } } } } } }, "responses": { "200": { "description": "Conversion calculated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "object", "properties": { "fromAmount": { "type": "number", "example": 15.0 }, "fromCurrency": { "type": "string", "example": "USD" }, "fromFormatted": { "type": "string", "example": "$15.00" }, "toAmount": { "type": "number", "example": 13.04 }, "toCurrency": { "type": "string", "example": "EUR" }, "toFormatted": { "type": "string", "example": "13,04 \u20ac" }, "spreadAmount": { "type": "number", "example": 0.12 }, "spreadCurrency": { "type": "string", "example": "EUR" }, "exchangeRateId": { "type": "string", "example": "01kkk4b7rh8pcvtw1s1nxs144s" }, "currencyPairName": { "type": "string", "example": "EUR/USD" }, "feeAmount": { "type": "number", "example": 0.0 }, "feeCurrency": { "type": "string", "example": "USD" } } } } } } } } } } }, "/v1/global-payout/exchange-rates": { "get": { "description": "Retrieve the latest exchange rates for a currency pair before initiating a transfer.", "operationId": "Fetch Exchange Rates", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "name": "from", "in": "query", "required": true, "description": "ISO 4217 currency code to convert from.", "schema": { "type": "string", "example": "EUR" } }, { "name": "to", "in": "query", "required": true, "description": "ISO 4217 currency code to convert to.", "schema": { "type": "string", "example": "USD" } }, { "name": "region", "in": "query", "required": false, "description": "Optional trade region filter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exchange rates retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "object", "properties": { "rates": { "type": "array", "items": { "type": "object", "properties": { "exchangeRateId": { "type": "string", "example": "01kkk7pab9mjt70wvk6pzk8mzx" }, "currencyPairName": { "type": "string", "example": "EUR/USD" }, "bidRate": { "type": "string", "example": "$1.13" }, "askRate": { "type": "string", "example": "$1.14" }, "midRate": { "type": "string", "example": "$1.14" }, "createdAt": { "type": "string", "example": "2026-03-13T09:15:57.161946" } } } } } } } } } } } } } }, "/v1/global-payout/transactions/{transactionId}": { "get": { "description": "Track the status of any Global Payout transaction using its transaction ID.", "operationId": "Fetch Global Payout Transaction", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "name": "transactionId", "in": "path", "required": true, "description": "The wtTransactionId returned when the transfer was authorized.", "schema": { "type": "string", "example": "01kj9ssfwqd4a97jhdx65gmyqy" } } ], "responses": { "200": { "description": "Transaction retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "object", "properties": { "transactionId": { "type": "string", "example": "01kj9ssfwqd4a97jhdx65gmyqy" }, "status": { "type": "string", "example": "PROCESSING", "enum": [ "PROCESSING", "COMPLETED", "FAILED", "PENDING" ] }, "coreStatus": { "type": "string", "example": "PAYMENT_SUCCESSFUL" }, "type": { "type": "string", "example": "TRANSFER" }, "createdAt": { "type": "string", "example": "2026-03-13T09:15:57.161946" } } } } } } } } } } }, "/v1/global-payout/payment-methods": { "get": { "description": "Returns all supported payment methods and their method-specific requirements. Filter by code or name to retrieve a specific method.", "operationId": "Fetch Payment Methods", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "Optional payment method code used to return a specific method.", "in": "query", "name": "code", "schema": { "type": "string", "example": "ACH" }, "required": false }, { "description": "Optional payment method name used to return a specific method, for example BANK or Wire Transfer.", "in": "query", "name": "name", "schema": { "type": "string", "example": "BANK" }, "required": false } ], "responses": { "200": { "description": "Payment methods retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "BANK" }, "displayName": { "type": "string", "example": "Bank Transfer" }, "purposeOfPaymentRequired": { "type": "boolean", "example": true }, "purposeOfPayments": { "type": "array", "items": { "type": "string" }, "example": [ "MAINTENANCE_EXPENSES", "SERVICE_CHARGES" ], "description": "Selectable purpose-of-payment values for this method." }, "requiredFields": { "type": "array", "items": { "type": "string" }, "example": [ "accountNumber", "institutionCode", "accountType", "bankAccountType", "beneficiary", "purposeOfPayment" ] }, "optionalFields": { "type": "array", "items": { "type": "string" }, "example": [ "narration" ] }, "accountTypes": { "type": "array", "items": { "type": "string" }, "example": [ "INDIVIDUAL", "CORPORATE" ], "description": "Selectable accountType values for this method." }, "bankAccountTypes": { "type": "array", "items": { "type": "string" }, "example": [ "CHECKING", "SAVINGS" ], "description": "Selectable bankAccountType values for this method." } } } } } } } } } } } }, "/v1/global-payout/bank/providers": { "get": { "description": "Returns available bank, institution, or mobile money providers. Use isMobileMoney=false for bank/institution providers and isMobileMoney=true for mobile money providers. Use code as institutionCode and displayName as institutionName in Authorize Transfer.", "operationId": "List Institution Providers", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "description": "Set to true to return mobile money providers. Set to false to return bank or institution providers.", "in": "query", "name": "isMobileMoney", "schema": { "type": "boolean", "example": false }, "required": false }, { "description": "ISO 3166-1 alpha-2 destination country code used to return providers for a specific country.", "in": "query", "name": "countryIsoCode", "schema": { "type": "string", "example": "US" }, "required": false } ], "responses": { "200": { "description": "Providers retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Success" }, "status": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "access_bank" }, "displayName": { "type": "string", "example": "Access Bank" } } } } } } } } } } } }, "/v1/global-collection/inflow/initiate": { "post": { "description": "Trigger a mobile money collection request from a customer.", "operationId": "Initiate Mobile Money Inflow", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phoneNumber", "callbackUrl", "amount", "currency", "topupVendor" ], "properties": { "phoneNumber": { "type": "string", "example": "0980802xxx" }, "callbackUrl": { "type": "string", "example": "https://your-server.com/webhook/collection" }, "amount": { "type": "number", "example": 10 }, "currency": { "type": "string", "example": "CDF" }, "topupVendor": { "type": "string", "example": "AIRTEL", "description": "Mobile money network provider (e.g. AIRTEL, MPESA)." }, "idempotencyKey": { "type": "string", "description": "A client-generated key used to safely retry the request without risk of duplicate charges. If not provided, the server generates one automatically and returns it in the response.", "example": "a8f3d2c1-5b9e-4f7a-b2d6-1c8e3f5a9d0b" } } } } } }, "responses": { "200": { "description": "Inflow initiated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "object", "properties": { "transactionReference": { "type": "string", "example": "a822e327-4bcd-40ec-ac61-ed3622eac000" }, "status": { "type": "string", "example": "PENDING" }, "message": { "type": "string", "example": "success" }, "idempotencyKey": { "type": "string", "description": "The idempotency key used for this request \u2014 either the value you provided or a server-generated UUID. Store this and include it on any retry.", "example": "a8f3d2c1-5b9e-4f7a-b2d6-1c8e3f5a9d0b" } } } } } } } } } } }, "/v1/global-collection/transactions/{transactionId}": { "get": { "description": "Retrieve the status of an initiated mobile money collection.", "operationId": "Fetch Collection Transaction", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true }, { "name": "transactionId", "in": "path", "required": true, "description": "The transactionReference returned when the inflow was initiated.", "schema": { "type": "string", "example": "a822e327-4bcd-40ec-ac61-ed3622eac000" } } ], "responses": { "200": { "description": "Transaction retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "object", "properties": { "transactionId": { "type": "string", "example": "a822e327-4bcd-40ec-ac61-ed3622eac000" }, "coreUserId": { "type": "string", "example": "xxxx-xxxx-4402-97c0-6c3824cxxxxx" }, "account": { "type": "string", "example": "0980802918" }, "status": { "type": "string", "example": "APPROVED", "enum": [ "PENDING", "APPROVED", "FAILED", "CANCELLED" ] }, "amount": { "type": "number", "example": 10.0 }, "currency": { "type": "string", "example": "CDF" } } } } } } } } } } }, "/v1/checkout/order/cancel": { "post": { "description": "Use this endpoint to cancel an incomplete or pending checkout order.", "operationId": "Cancel checkout order", "summary": "Cancel Checkout Order", "tags": [ "Online Checkout" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderRequest" } } }, "description": "The request payload required to cancel a checkout order.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00", "description": "Response Code" }, "description": { "type": "string", "example": "success", "description": "Response description" }, "data": { "$ref": "#/components/schemas/CancelOrderResponse" } }, "required": [ "code", "description", "data" ] } } }, "description": "OK - your request was successful.", "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "string", "example": "40" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "string", "example": "39" } }, "X-Rate-Limit-Window": { "description": "The specified rate limit window", "schema": { "type": "string", "example": "1s" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }, "description": "The request body sent by merchant did not pass the validation checks" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" } } }, "description": "The access_token provided to access the resource is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationError" } } }, "description": "The client does not have the permissions to access this resource" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordNotFoundError" } } }, "description": "The record that the client is trying to access does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The client has maxed out the number of calls within a time period on this resource." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } }, "description": "Downstream system error." } } } }, "/v1/global-collection/drc/inflow/providers": { "get": { "description": "Returns the list of mobile money providers supported for DRC inflow. Use the returned code values as the topupVendor in the Initiate Mobile Money Inflow request.", "operationId": "Fetch DRC Inflow Providers", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "responses": { "200": { "description": "List of DRC inflow providers returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The provider code to use as topupVendor when initiating an inflow.", "example": "AIRTEL" }, "displayName": { "type": "string", "description": "Human-readable name of the provider.", "example": "Airtel Money" } } }, "example": [ { "code": "MPESA", "displayName": "Mpesa" }, { "code": "AIRTEL", "displayName": "Airtel Money" }, { "code": "ORANGE", "displayName": "Orange Money" } ] } } } } } } } } }, "/v1/sandbox/global-collection/drc/inflow/providers": { "get": { "description": "Sandbox version of Fetch DRC Inflow Providers. Returns the same static list of mobile money providers supported for DRC inflow for use in testing.", "operationId": "Fetch DRC Inflow Providers (Sandbox)", "parameters": [ { "description": "Bearer token for authentication.", "in": "header", "name": "Authorization", "schema": { "type": "string", "example": "Bearer " }, "required": true }, { "description": "The parent accountId of the business.", "in": "header", "name": "accountId", "schema": { "type": "string", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "required": true } ], "responses": { "200": { "description": "List of DRC inflow providers returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "Successful" }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "AIRTEL" }, "displayName": { "type": "string", "example": "Airtel Money" } } }, "example": [ { "code": "MPESA", "displayName": "Mpesa" }, { "code": "AIRTEL", "displayName": "Airtel Money" }, { "code": "ORANGE", "displayName": "Orange Money" } ] } } } } } } } } } }, "components": { "schemas": { "AirtimePurchaseRequest": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "The airtime amount to be purchased", "example": 200 }, "phoneNumber": { "type": "string", "description": "Recipient phone number", "minLength": 11, "maxLength": 13, "example": "08055441122" }, "network": { "type": "string", "description": "Recipient network (telco). It can also come as lowercased values e.g. glo, mtn etc.", "minLength": 3, "enum": [ "GLO", "MTN", "9MOBILE", "AIRTEL" ], "example": "GLO" }, "merchantTxRef": { "type": "string", "description": "Merchant Transaction Identifier reference (Unique to merchant) \n \n This is an idempotency key and must be unique per transaction.", "example": "3bvwhibh38220dsjakTwvb" }, "senderName": { "type": "string", "description": "A name to describe the sender of the airtime", "example": "John Doe" } }, "required": [ "amount", "phoneNumber", "network", "merchantTxRef" ] }, "AirtimePurchaseResponse": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "The airtime amount to be purchased", "example": 200 }, "timeCreated": { "type": "string", "description": "The Date and Time of transaction creation", "format": "date-time", "example": "2023-09-04T07:09:06.900Z" }, "type": { "type": "string", "description": "The classification for this type of transaction", "example": "topup" }, "meta": { "type": "object", "description": "Extra information about this transaction", "example": { "merchantTxRef": "test1116", "rrn": "240626232937" } }, "status": { "type": "string", "description": "The system status of this transction", "example": "Processing" } }, "required": [ "amount", "timeCreated", "type", "status" ] }, "DataVendingRequest": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "The data amount to be vended", "example": 200 }, "phoneNumber": { "type": "string", "description": "Recipient phone number", "minLength": 11, "maxLength": 13, "example": "08055441122" }, "network": { "type": "string", "description": "Recipient network (telco). It can also come as lowercased values e.g. glo, mtn etc.", "minLength": 3, "enum": [ "GLO", "MTN", "9MOBILE", "AIRTEL" ], "example": "GLO" }, "merchantTxRef": { "type": "string", "description": "Merchant Transaction Identifier reference (Unique to merchant)", "example": "3bvwhibh38220dsjakTwvb" }, "senderName": { "type": "string", "description": "A name to describe the sender of the data", "example": "John Doe" } }, "required": [ "amount", "phoneNumber", "network", "merchantTxRef" ] }, "DataVendingResponse": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "The airtime amount to be purchased", "example": 200 }, "timeCreated": { "type": "string", "description": "The Date and Time of transaction creation", "format": "date-time", "example": "2023-09-04T07:09:06.900Z" }, "type": { "type": "string", "description": "The classification for this type of transaction", "example": "topup" }, "meta": { "type": "object", "description": "Extra information about this transaction", "example": { "merchantTxRef": "test1116", "rrn": "240626232937" } }, "status": { "type": "string", "description": "The system status of this transction", "example": "Processing" } }, "required": [ "amount", "timeCreated", "type", "status" ] }, "CheckoutTransaction": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True if the transaction is already completed and successful, false otherwise", "example": "true" }, "message": { "type": "string", "description": "Response message describing the transaction status", "example": "success" }, "order": { "$ref": "#/components/schemas/OrderDetails" }, "transactionDetails": { "$ref": "#/components/schemas/CheckoutTransactionDetails" }, "transferDetails": { "$ref": "#/components/schemas/CheckoutTransferDetails" }, "cardDetails": { "$ref": "#/components/schemas/CheckoutCardDetails" } } }, "OrderDetailsObject": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Id generated by Nomba for the checkout order", "example": "56e03654-0c32-4d3e-bbd6-a9df22994a12" }, "orderReference": { "type": "string", "description": "Reference of the online checkout order to be created", "example": "90e81e8a-bc14-4ebf-89c0-57da752cca58" }, "customerId": { "type": "string", "description": "Customer id", "example": "762878332454" }, "accountId": { "type": "string", "description": "The account Id whose wallet will be credited when the order is paid", "example": "56e03654-0c32-4d3e-bbd6-a9df22994a12" }, "callbackUrl": { "type": "string", "description": "Merchant callback url for redirect after payment", "example": "https://ip:port/merchant.com/callback" }, "customerEmail": { "type": "string", "description": "Customer email", "example": "abcde@gmail.com" }, "amount": { "type": "number", "format": "double", "description": "Amount to pay", "example": "10000.00" }, "currency": { "type": "string", "description": "Currency of the money", "enum": [ "NGN" ], "example": "NGN" }, "businessName": { "type": "string", "description": "Business Name", "example": "Merchant Ltd" }, "businessEmail": { "type": "string", "description": "Business email", "example": "abcde@gmail.com" }, "businessLogo": { "type": "string", "description": "Link to business logo", "example": "https://ip:port/merchant.com/logo" } } }, "GetOrderDetails": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/OrderDetailsObject" }, "hasSavedCards": { "type": "boolean", "description": "true if the user has saved cards", "example": "true" }, "base64EncodedRsaPublicKey": { "type": "string", "description": "Base64 encoded RSA public key, returned if data encryption is enabled to submit the card details, else an empty string", "example": "5844858382" } } }, "DeviceInformation": { "type": "object", "description": "Contains browser information for the device making the api calls", "properties": { "httpBrowserLanguage": { "type": "string", "description": "Browser language", "example": "en-GB" }, "httpBrowserJavaEnabled": { "type": "boolean", "description": "true if Java is enabled in the browser in use", "example": "true" }, "httpBrowserJavaScriptEnabled": { "type": "boolean", "description": "true if Javascript is enabled in the browser in use", "example": "true" }, "httpBrowserColorDepth": { "type": "string", "description": "Browser color depth", "example": "30" }, "httpBrowserScreenHeight": { "type": "string", "description": "Browser scren height", "example": "900" }, "httpBrowserScreenWidth": { "type": "string", "description": "Browser screen weidth", "example": "1500" }, "httpBrowserTimeDifference": { "type": "string", "description": "Browser time difference", "example": "-60" }, "userAgentBrowserValue": { "type": "string", "description": "Browser user agent", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" }, "deviceChannel": { "type": "string", "description": "Device channel", "example": "Browser" } } }, "SecureAuthenticationData": { "type": "object", "description": "Authentication data returned from the payment gateway when the payment card requires 3D Secure authentication. This data will be passed to the", "properties": { "jwt": { "type": "string", "description": "jwt token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }, "md": { "type": "string", "description": "encryption key is data encrption is in use, else empty string", "example": "6775843012" }, "acsUrl": { "type": "string", "description": "the order reference returned when the order was created", "example": "https://ip:port/merchant.com/callback" }, "termUrl": { "type": "string", "description": "the order reference returned when the order was created", "example": "https://ip:port/merchant.com/callback" } } }, "SubmitCardDetails": { "type": "object", "properties": { "cardDetails": { "type": "string", "description": "Stringified card details", "example": { "cardCVV": 11, "cardExpiryMonth": 3, "cardExpiryYear": 2050, "cardNumber": "5190752909999995", "cardPin": 1111 } }, "key": { "type": "string", "description": "encryption key is data encrption is in use, else empty string", "example": "" }, "orderReference": { "type": "string", "description": "the order reference returned when the order was created", "example": "c4307d58-2513-41d8-b7f7-dfecd5f9fdbe" }, "saveCard": { "type": "boolean", "description": "if true, this this user cardn will be saved for the user's future use. Note the process is not complete until the user-card verification endpoints are called to authenticate the user's phone number.", "example": "true" }, "deviceInformation": { "$ref": "#/components/schemas/DeviceInformation" } } }, "SubmitCardDetailsResponse": { "type": "object", "properties": { "status": { "type": "boolean", "description": "true if the card details were submitted successfully", "example": "true" }, "message": { "type": "string", "description": "Response message describing the transaction status or further instruction for the user like the case of OTP", "example": "Success" }, "responseCode": { "type": "string", "description": "response code from the payment gate way. 00 means transaction was successful and completed, T0 means an OTP has been sent to the user and should be entered next, SO means 3D Secure authentication is required and the client application needs to redirect to the 3D secure page based on the information provided in the secureAuthenticationData field", "example": "00" }, "transactionId": { "type": "string", "description": "the unique id of the transaction just created by the submittion of the card details. This value should be passed back to all API calls that require it.", "example": "c4307d58-2513-41d8-b7f7-dfecd5f9fdbe" }, "secureAuthenticationData": { "$ref": "#/components/schemas/SecureAuthenticationData" } } }, "SubmitCardOTP": { "type": "object", "properties": { "otp": { "type": "string", "description": "otp send to the customer's mobile phone", "example": "1234" }, "orderReference": { "type": "string", "description": "order reference", "example": "c4307d58-2513-41d8-b7f7-dfecd5f9fdbe" }, "transactionId": { "type": "string", "description": "transaction id returend when the card details were submitted", "example": "c4307d58-2513-41d8-b7f7-dfecd5f9fdbe" } }, "required": [ "otp", "orderReference", "transactionId" ] }, "SubmitCardOTPResponse": { "type": "object", "properties": { "status": { "type": "boolean", "description": "true is the transaction was successful", "example": "true" }, "message": { "type": "string", "description": "details response message", "example": "success" } }, "required": [ "status", "message" ] }, "CheckoutDataRequest": { "type": "object", "properties": { "orderReference": { "type": "string", "description": "order reference", "example": "c4307d58-2513-41d8-b7f7-dfecd5f9fdbe" } }, "required": [ "orderReference" ] }, "CheckoutDataResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "true is the transaction was successful", "example": "true" }, "message": { "type": "string", "description": "details response message", "example": "success" } }, "required": [ "success", "message" ] }, "CheckoutTransactionDetailsResponse": { "type": "object", "properties": { "status": { "type": "boolean", "description": "true is the transaction was successful", "example": "true" }, "message": { "type": "string", "description": "details response message", "example": "success" }, "order": { "$ref": "#/components/schemas/OrderDetailsObject" } }, "required": [ "status", "message" ] }, "CheckoutAccountNumberResponse": { "type": "object", "properties": { "accountNumber": { "type": "string", "description": "true is the transaction was successful", "example": "5678576432" }, "accountName": { "type": "string", "description": "account name", "example": "Femi Fash" }, "bankName": { "type": "string", "description": "Bank name", "example": "Nombank Mfb" } }, "required": [ "accountNumber", "accountName", "bankName" ] }, "CheckoutAuthenticateUserRequest": { "type": "object", "properties": { "orderReference": { "type": "string", "description": "order reference", "example": "c4307d58-2513-41d8-b7f7-dfecd5f9fdbe" }, "phoneNumber": { "type": "string", "description": "customer's phone number", "example": "08012345678" } }, "required": [ "orderReference", "phoneNumber" ] }, "CheckoutSubmitUserOTPRequest": { "type": "object", "properties": { "orderReference": { "type": "string", "description": "order reference", "example": "c4307d58-2513-41d8-b7f7-dfecd5f9fdbe" }, "phoneNumber": { "type": "string", "description": "customer's phone number", "example": "08012345678" }, "otp": { "type": "string", "description": "otp send to the customer's mobile phone", "example": "1234" } }, "required": [ "orderReference", "phoneNumber", "otp" ] }, "CheckoutCancelTransactionRequest": { "type": "object", "properties": { "transactionId": { "type": "string", "description": "the transaction Id returned when the card details were submitted", "example": "c4307d58-2513-41d8-b7f7-dfecd5f9fdbe" }, "forceCancel": { "type": "boolean", "description": "Force the cancelation of the transaction", "example": "false" } }, "required": [ "transactionId", "forceCancel" ] }, "TokenizedCardDataList": { "type": "object", "properties": { "tokenizedCardData": { "items": { "$ref": "#/components/schemas/TokenizedCardData" } } } }, "OrderDetails": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Id generated by Nomba for the checkout order", "example": "56e03654-0c32-4d3e-bbd6-a9df22994a12" }, "orderReference": { "type": "string", "description": "Reference of the online checkout order to be created", "example": "90e81e8a-bc14-4ebf-89c0-57da752cca58" }, "customerId": { "type": "string", "description": "Customer id", "example": "762878332454" }, "accountId": { "type": "string", "description": "The account Id whose wallet will be credited when the order is paid", "example": "56e03654-0c32-4d3e-bbd6-a9df22994a12" }, "callbackUrl": { "type": "string", "description": "Merchant callback url for redirect after payment", "example": "https://ip:port/merchant.com/callback" }, "customerEmail": { "type": "string", "description": "Customer email", "example": "abcde@gmail.com" }, "amount": { "type": "number", "format": "double", "description": "Amount to pay", "example": "10000.00" }, "currency": { "type": "string", "description": "Currency of the money", "enum": [ "NGN" ], "example": "NGN" } } }, "CheckoutTransactionDetails": { "type": "object", "properties": { "transactionDate": { "type": "string", "format": "date-time", "description": "Date the transaction was created", "example": "2023-12-06T15:46:43.000Z" }, "paymentReference": { "type": "string", "description": "The payment reference for the transaction", "example": "5844858382134" }, "paymentVendorReference": { "type": "string", "description": "The payment reference returned by the payment gateway", "example": "5844858382675493" }, "tokenizedCardPayment": { "type": "boolean", "description": "True if the payment was made by a tokenized card", "example": "true" }, "statusCode": { "type": "string", "description": "transaction status code returned by the payment gateway", "example": "Payment approved" } } }, "CheckoutTransferDetails": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Transfer sessionId", "example": "67584432178569543" }, "beneficiaryAccountName": { "type": "string", "description": "The account name associated with the Merchants Nombank account", "example": "Tope Fade" }, "beneficiaryAccountNumber": { "type": "string", "description": "The Flash account number, where the payment was made to", "example": "5844858382" }, "originatorAccountName": { "type": "string", "description": "The name of the person making the transfer", "example": "Femi Fash" }, "originatorAccountNumber": { "type": "string", "description": "Nuban account number of the person making the transfer", "example": "3409082834" }, "narration": { "type": "string", "description": "The naration added by the customer when making the transfer", "example": "Checkout payment" }, "destinationInstitutionCode": { "type": "string", "description": "Destination bank code", "example": "true" }, "paymentReference": { "type": "string", "description": "Transfer payment reference passed in from NIBSS for the transfer", "example": "44384586756" } } }, "CheckoutCardDetails": { "type": "object", "properties": { "cardPan": { "type": "string", "description": "The masked card pan", "example": "515123 **** **** 6667" }, "cardType": { "type": "string", "description": "The Card type", "example": "Verve" }, "cardCurrency": { "type": "string", "description": "The card currency", "example": "NGN" }, "cardBank": { "type": "string", "description": "Card Bank code", "example": "057" } } }, "DeleteTokenizedCardDataRequest": { "type": "object", "properties": { "tokenKey": { "type": "string", "description": "token key", "example": "5844858382" } }, "required": [ "tokenKey" ] }, "DeleteTokenizedCardDataResponse": { "type": "object", "properties": { "status": { "type": "boolean", "description": "status", "example": "true" }, "message": { "type": "string", "description": "Response message", "example": "success" } } }, "UpdateTokenizedCardDataRequest": { "type": "object", "properties": { "tokenKey": { "type": "string", "description": "token key", "example": "5844858382" }, "currentEmailAddress": { "type": "string", "description": "customer email currently associated with the key", "example": "email@email.com" }, "newEmailAddress": { "type": "string", "description": "new email to replace the old one", "example": "email@email.com" } }, "required": [ "tokenKey", "currentEmailAddress", "newEmailAddress" ] }, "UpdateTokenizedCardDataResponse": { "type": "object", "properties": { "status": { "type": "boolean", "description": "status", "example": "true" }, "message": { "type": "string", "description": "customer email currently associated with the key", "example": "email@email.com" }, "tokenizedCardData": { "items": { "$ref": "#/components/schemas/TokenizedCardData" } } } }, "CreateOrderResponse": { "type": "object", "properties": { "checkoutLink": { "type": "string", "description": "Payment checkout link", "example": "https://ip:port/checkout/78388899938" }, "orderReference": { "type": "string", "description": "The reference of the order created", "example": "90e81e8a-bc14-4ebf-89c0-57da752cca58" } }, "required": [ "checkoutLink", "orderReference" ] }, "Order": { "type": "object", "properties": { "orderReference": { "type": "string", "description": "reference of the online checkout order to be created", "example": "90e81e8a-bc14-4ebf-89c0-57da752cca58" }, "customerId": { "type": "string", "description": "customer id", "example": "762878332454" }, "callbackUrl": { "type": "string", "description": "Merchant callback url for redirect after payment", "example": "https://ip:port/merchant.com/callback" }, "customerEmail": { "type": "string", "description": "customer email", "example": "abcde@gmail.com" }, "amount": { "type": "number", "format": "double", "description": "Amount to pay", "example": "10000.00" }, "currency": { "type": "string", "description": "ISO 4217 currency code. Use NGN for Nigerian checkout. For DRC accounts, use CDF or USD \u2014 NGN is not supported for DRC and will be rejected.", "enum": [ "NGN", "CDF", "USD" ], "example": "NGN" }, "accountId": { "type": "string", "description": "If specified, this is the account where the funds will be deposited.", "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "allowedPaymentMethods": { "type": "array", "description": "Optional list of payment methods to display on the checkout page. If not provided, all supported methods for your account and region will be shown. Supported values: Card, Transfer, Nomba QR, USSD, Buy Now Pay Later (Nigerian checkout); MOMO, Intl Card, Apple Pay (DRC checkout).", "items": { "type": "string", "enum": [ "Card", "Transfer", "Nomba QR", "USSD", "Buy Now Pay Later", "MOMO", "Intl Card", "Apple Pay" ] }, "example": [ "Card", "Transfer" ] }, "splitRequest": { "type": "object", "description": "Contains accounts where the inflow will be split into", "properties": { "splitType": { "type": "string", "description": "The type fo split to use, either PERCENTAGE or AMOUNT", "enum": [ "PERCENTAGE", "AMOUNT" ] }, "splitList": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "description": "The account Id whose wallet will be credited when the order is paid", "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "value": { "type": "number", "description": "The percentage or the order amount or the actual value to credit to this account.", "example": "65.45" } } } } } }, "orderMetaData": { "type": "object", "description": "Arbitrary key-value metadata to attach to the order. Keys and values must be strings. Stored on the order and returned in webhook payloads. Special key: set \"region\" to \"CD\" to route this order through DRC checkout (e.g. for a Nigerian merchant accepting DRC MoMo payments).", "additionalProperties": { "type": "string" }, "example": { "productName": "Premium Plan", "internalRef": "INV-2026-001", "region": "CD" } } }, "required": [ "callbackUrl", "customerEmail", "amount", "currency" ] }, "CreateOrderRequest": { "type": "object", "description": "The Checkout request object", "properties": { "order": { "$ref": "#/components/schemas/Order" }, "tokenizeCard": { "type": "boolean", "description": "Determines if the card used for payment is to be tokenized", "example": "true" } }, "required": [ "order" ] }, "TokenizedCardPaymentRequest": { "type": "object", "description": "The Tokenized card payment request object", "properties": { "order": { "$ref": "#/components/schemas/Order" }, "tokenKey": { "type": "string", "description": "the token key returned in the webhook", "example": "7628788443" } }, "required": [ "tokenKey" ] }, "TokenizedCardPaymentResponse": { "type": "object", "properties": { "status": { "type": "boolean", "description": "status of the transaction", "example": "true" }, "message": { "type": "string", "description": "some details of the transaction response.", "example": "success" } } }, "RefundCheckoutTransactionRequestDTO": { "type": "object", "description": "The request object for refunding a checkout transaction", "properties": { "transactionId": { "type": "string", "description": "The ID of the transaction to be refunded", "example": "TXN-123456789" }, "amount": { "type": "number", "format": "double", "description": "The amount to be refunded", "example": 5000.0 }, "accountNumber": { "type": "string", "description": "The account number for the refund", "example": "0123456789", "maxLength": 10, "minLength": 10 }, "bankCode": { "type": "string", "description": "The bank code for the refund", "example": "058" } }, "required": [ "transactionId" ] }, "CheckoutDataResponseDTO": { "type": "object", "description": "The response object for checkout operations", "properties": { "success": { "type": "boolean", "description": "Indicates whether the operation was successful", "example": true }, "message": { "type": "string", "description": "A message describing the result of the operation", "example": "Refund processed successfully" } }, "required": [ "success", "message" ] }, "TokenizedCardData": { "type": "object", "properties": { "tokenKey": { "type": "string", "description": "the key associated with the tokenzied card", "example": "e890bd1a9f0d" }, "customerEmail": { "type": "string", "description": "customer email", "example": "email@email.com" }, "cardType": { "type": "string", "description": "Unique reference used to track an account from an external process. Would be auto-generated if not provided at the point of creation.", "example": "Verve" }, "cardPan": { "type": "string", "description": "Card pan", "example": "234818********7580" }, "tokenExpirationDate": { "type": "string", "description": "token expiration date", "example": "20/20" } } }, "BankAccountTransferMetaObject": { "type": "object", "properties": { "api_rrn": { "type": "string", "description": "API RRN", "example": "2309081xxxxxx" }, "narration": { "type": "string", "description": "Transfer naration", "example": "Testing" }, "recipientName": { "type": "string", "description": "Fund recipient name", "example": "John doe" }, "sender_name": { "type": "string", "description": "Name of transfer initiator", "example": "Nightly Post" }, "merchantTxRef": { "type": "string", "description": "Merchant transaction reference", "example": "3JVW2xJCjj443oannREBuTaXDdji" }, "api_client_id": { "type": "string", "description": "API client ID", "example": "6a7bed88-7c93-4a1c-a445-f88edbca6489" }, "currency": { "type": "string", "description": "Currency code", "example": "NGN" }, "hooksEligible": { "type": "string", "description": "Hooks eligible", "example": "true" }, "banking_entity_id": { "type": "string", "description": "API account ID", "example": "842f2b4320f" }, "banking_entity_user_id": { "type": "string", "description": "API account ID", "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "banking_entity_type": { "type": "string", "description": "Bank entity type", "example": "9842f2b4320f" }, "self_transaction": { "type": "string", "description": "Self transaction", "example": "true" }, "transactionCategory": { "type": "string", "description": "Family and Kids", "example": "128735648" }, "accountNumber": { "type": "string", "description": "API account ID", "example": "0127667384" }, "bankName": { "type": "string", "description": "Recipient bank name", "example": "GTbank" }, "bankCode": { "type": "string", "description": "Bank code", "example": "058" }, "sessionId": { "type": "string", "description": "Session ID", "example": "" }, "user_referral_code": { "type": "string", "description": "Referral code", "example": "HABI76745" }, "amount_charged": { "type": "string", "description": "Amount charged", "example": "21.0" }, "paymentVendor": { "type": "string", "description": "Paytment vendor type", "example": "Wallet" }, "wallet_balance": { "type": "string", "description": "Wallet balance", "example": "5.38" }, "wallet_currency": { "type": "string", "description": "Currency code for the payment", "example": "NGN" }, "paymentVendorReference": { "type": "string", "description": "Payment vendor reference", "example": "01a10aeb-d989-460a-bbde-9840f" }, "agent_commission": { "type": "string", "description": "Agent commision", "example": "0.0" }, "useV2Fulfilment": { "type": "string", "description": "check fulfulment value", "example": "true" } }, "description": "Transaction meta data" }, "BankAccountTransferRequest": { "type": "object", "description": "A structure representing an object required to post a bank account transfer.", "properties": { "amount": { "type": "number", "format": "double", "description": "The amount to be transferred.", "example": 3500 }, "accountNumber": { "type": "string", "description": "The destination bank account number.", "example": "0554772814", "maxLength": 10, "minLength": 10 }, "accountName": { "type": "string", "description": "The name on the account.", "example": "M.A Animashaun" }, "bankCode": { "type": "string", "description": "The code of the recipient bank.", "example": "058" }, "merchantTxRef": { "type": "string", "description": "Unique reference used to track a transaction from an external process. \n \nThis is an idempotency key and must be unique per transaction.", "example": "UNQ_123abGGhh5546" }, "senderName": { "type": "string", "description": "Sender name", "example": "Nightly Post" }, "narration": { "type": "string", "description": "The payment narration", "example": "Testing Payment" } }, "required": [ "amount", "accountNumber", "bankCode", "accountName", "merchantTxRef" ] }, "BankAccountTransferResult": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount to be transfer", "example": "1.0" }, "source": { "type": "string", "description": "Trnsfer source could be web, api etc..", "example": "api" }, "sourceUserId": { "type": "string", "description": "Source user ID", "example": "11ec45a1-1fe5-44f5-8baf-cxxxxxxxxxx" }, "customerBillerId": { "type": "string", "description": "Customer biller ID", "example": "010784xxxx" }, "productId": { "type": "string", "description": "A unique number for the product", "example": "058" }, "meta": { "$ref": "#/components/schemas/BankAccountTransferMetaObject" }, "fee": { "type": "number", "format": "double", "description": "Transfer fee", "example": 50.0 }, "timeCreated": { "type": "string", "format": "date-time", "description": "Creation timestamp", "example": "2026-03-08T14:17:13.634Z" }, "id": { "type": "string", "description": "Transfer ID", "example": "API-TRANSFER-C24AD-a6443bf0-011c-4bc2-b739-4a2e33e2a27b" }, "type": { "type": "string", "description": "Transaction type", "enum": [ "withdrawal", "purchase", "transfer", "p2p", "online_checkout", "qrt_credit", "qrt_debit" ], "example": "transfer" }, "status": { "type": "string", "description": "Transaction status", "enum": [ "SUCCESS", "PENDING_BILLING" ], "example": "SUCCESS" } }, "required": [ "amount", "meta", "fee", "timeCreated", "id", "type", "status" ], "description": "Transfer data" }, "BankAccountLookupRequest": { "type": "object", "description": "A structure representing a bank account lookup request", "properties": { "accountNumber": { "type": "string", "description": "The account number to be looked up.", "example": "0554772814", "maxLength": 10, "minLength": 10 }, "bankCode": { "type": "string", "description": "The bankCode of the bank the account number belongs to. This can be obtained from a call to `/v1/transfers/banks` ", "example": "053" } }, "required": [ "accountNumber", "bankCode" ] }, "BankAccountLookupResult": { "type": "object", "description": "A structure representing a bank account lookup result", "properties": { "accountNumber": { "type": "string", "description": "The account number already looked up.", "example": "0554772814", "maxLength": 10, "minLength": 10 }, "accountName": { "type": "string", "description": "The name on the account.", "example": "M.A Animashaun" } } }, "Banks": { "type": "object", "description": "A structure representing a bank", "properties": { "code": { "type": "string", "description": "The bank's code.", "example": "058", "maxLength": 6, "minLength": 3 }, "name": { "type": "string", "description": "The bank's name.", "example": "Guaranty Trust Bank" } } }, "BanksListResults": { "type": "object", "properties": { "results": { "type": "array", "description": "Contains result of all banks fetched", "items": { "$ref": "#/components/schemas/Banks" } } } }, "CreateAccountRequest": { "type": "object", "properties": { "accountRef": { "type": "string", "description": "Account reference", "minLength": 16, "maxLength": 64, "example": "1oWbJQQHLyQqqf1SwxjSpudeA21" }, "phoneNumber": { "type": "string", "description": "Phone number", "minLength": 11, "maxLength": 15, "example": "2348188667581" }, "email": { "type": "string", "description": "Email address", "format": "email", "example": "ifeol-subaccount@exmple.com" }, "bvn": { "type": "string", "description": "Bank Verification Number (BVN)", "minLength": 11, "maxLength": 11, "example": "12234412345" }, "pin": { "type": "string", "description": "Personal Identification Number (PIN)", "minLength": 4, "maxLength": 4, "example": "1234" }, "accountName": { "type": "string", "description": "Account holder's name", "minLength": 8, "maxLength": 64, "example": "Daniel Scorsese" }, "currency": { "type": "string", "description": "Currency code", "minLength": 3, "maxLength": 3, "enum": [ "NGN" ], "example": "NGN" }, "callbackUrl": { "type": "string", "description": "Callback url", "format": "url", "example": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7" }, "expiryDate": { "type": "string", "format": "date-time", "description": "Expiry date", "example": "2023-12-06T15:46:43.000Z" } }, "required": [ "accountRef", "phoneNumber", "email", "bvn", "pin", "accountName", "currency" ] }, "CreateAccountResponse": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Creation timestamp", "format": "date-time", "example": "2023-09-04T07:09:06.900Z" }, "accountId": { "type": "string", "description": "Account ID", "minLength": 36, "maxLength": 36, "example": "fc81b80e-e607-4b86-8591-840925191733" }, "accountHolderId": { "type": "string", "description": "Account holder ID", "minLength": 36, "maxLength": 36, "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "accountRef": { "type": "string", "description": "Account reference", "minLength": 16, "maxLength": 64, "example": "1oWbJQQHLyQqqf1SwxjSpudeA21" }, "phoneNumber": { "type": "string", "description": "Phone number", "minLength": 11, "maxLength": 15, "example": "2348188667581" }, "email": { "type": "string", "description": "Email address", "format": "email", "example": "ifeol-subaccount-4@exmple.com" }, "bvn": { "type": "string", "description": "Bank Verification Number (BVN)", "minLength": 11, "maxLength": 11, "example": "12234412345" }, "status": { "type": "string", "description": "Account status", "enum": [ "ACTIVE", "INACTIVE", "SUSPENDED", "PND", "BLACKLISTED" ], "example": "ACTIVE" }, "type": { "type": "string", "description": "Account type", "enum": [ "virtual", "outlet" ], "example": "virtual" }, "accountName": { "type": "string", "description": "Account holder's name", "minLength": 8, "maxLength": 64, "example": "Daniel Scorsese" }, "currency": { "type": "string", "description": "Currency code", "minLength": 3, "maxLength": 3, "enum": [ "NGN" ], "example": "NGN" }, "callbackUrl": { "type": "string", "description": "Callback url", "format": "url", "example": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7" }, "expiryDate": { "type": "string", "format": "date-time", "description": "Expiry date", "example": "2023-12-06T15:46:43.000Z" } }, "required": [ "createdAt", "accountId", "accountHolderId", "accountRef", "phoneNumber", "email", "bvn", "status", "type", "accountName", "currency" ] }, "CreateVirtualAccountRequest": { "type": "object", "properties": { "accountRef": { "type": "string", "description": "Account reference", "minLength": 16, "maxLength": 64, "example": "1oWbJQQHLyQqqf1SwxjSpudeA21" }, "accountName": { "type": "string", "description": "Account holder's name", "minLength": 8, "maxLength": 64, "example": "Daniel Scorsese" }, "bvn": { "type": "string", "description": "Account holder's BVN. Optional.", "example": "12345678" }, "expiryDate": { "type": "string", "description": "Account expiry date. Optional. \u26a0\ufe0fBe careful with this.", "example": "2026-01-30 12:15:00" }, "expectedAmount": { "type": "number", "format": "double", "description": "Amount the account can receive. Optional.", "example": "200.00" } }, "required": [ "accountRef", "accountName" ] }, "CreateVirtualAccountResponse": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Creation timestamp", "format": "date-time", "example": "2023-09-04T07:09:06.900Z" }, "accountHolderId": { "type": "string", "description": "Account holder ID", "minLength": 36, "maxLength": 36, "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "accountRef": { "type": "string", "description": "Account reference", "minLength": 16, "maxLength": 64, "example": "1oWbJQQHLyQqqf1SwxjSpudeA21" }, "bvn": { "type": "string", "description": "Bank Verification Number (BVN)", "minLength": 11, "maxLength": 11, "example": "12234412345" }, "accountName": { "type": "string", "description": "Account holder's name", "minLength": 8, "maxLength": 64, "example": "Daniel Scorsese" }, "bankName": { "type": "string", "description": "Bank name", "example": "Nombank MFB" }, "bankAccountNumber": { "type": "string", "description": "Bank account number", "example": "9391076543" }, "bankAccountName": { "type": "string", "description": "Bank account holder name", "example": "Nomba/Ifeoluwa Adeboye" }, "currency": { "type": "string", "description": "Currency code", "minLength": 3, "maxLength": 3, "enum": [ "NGN" ], "example": "NGN" }, "callbackUrl": { "type": "string", "description": "Callback url", "format": "url", "example": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7" }, "expired": { "type": "boolean", "description": "Successfully updated", "example": true } }, "required": [ "createdAt", "accountId", "accountHolderId", "accountRef", "bvn", "status", "type", "accountName", "banks", "currency" ] }, "FilterVirtualAccountRequest": { "type": "object", "properties": { "accountName": { "type": "string", "description": "Account holder's name", "minLength": 8, "maxLength": 64, "example": "Daniel Scorsese" }, "accountRef": { "type": "string", "description": "Account reference", "minLength": 16, "maxLength": 64, "example": "1oWbJQQHLyQqqf1SwxjSpudeA21" }, "bvn": { "type": "string", "description": "Bank Verification Number (BVN)", "minLength": 11, "maxLength": 11, "example": "12234412345" }, "bankAccountNumber": { "type": "string", "description": "Bank account number", "example": "9391076543" }, "dateCreatedFrom": { "type": "string", "format": "date-time", "description": "Date created from", "example": "2023-08-30T14:56:59.000Z" }, "dateCreatedTo": { "type": "string", "format": "date-time", "description": "Date created to", "example": "2024-08-30T14:56:59.000Z" }, "expired": { "type": "boolean", "description": "Whether the virtual account is expired or not", "example": false }, "resourceAcquired": { "type": "boolean", "description": "Whether the virtual account is in use or not", "example": false } } }, "UpdateVirtualAccountRequest": { "type": "object", "properties": { "newAccountRef": { "type": "string", "description": "The new accountReference you want to issue to the Virtual account. This will be the value advised in webhook post update", "minLength": 8, "maxLength": 64, "example": "INVOICE_20230908_0001" }, "accountName": { "type": "string", "description": "Account holder's name you want to update to", "minLength": 8, "maxLength": 64, "example": "Daniel Scorsese" }, "expectedAmount": { "type": "string", "description": "If provided, the virtual account will only accept payments that exactly match the specified amount.\n\nOnce expectedAmount is set, the virtual account will no longer accept arbitrary payment amounts.\nYou can, however, update the expectedAmount value at any time to change the accepted amount.", "example": "100.0" } } }, "UpdateVirtualAccountResponse": { "type": "object", "properties": { "updated": { "type": "boolean", "description": "Successfully updated", "example": true } }, "required": [ "updated" ] }, "ExpireVirtualAccountResponse": { "type": "object", "properties": { "expired": { "type": "boolean", "description": "Successfully updated", "example": true } }, "required": [ "expired" ] }, "VirtualAccountObject": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Creation timestamp", "format": "date-time", "example": "2023-09-04T07:09:06.900Z" }, "accountHolderId": { "type": "string", "description": "Account holder ID", "minLength": 36, "maxLength": 36, "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "accountRef": { "type": "string", "description": "Account reference", "minLength": 16, "maxLength": 64, "example": "1oWbJQQHLyQqqf1SwxjSpudeA21" }, "bvn": { "type": "string", "description": "Bank Verification Number (BVN)", "minLength": 11, "maxLength": 11, "example": "12234412345" }, "accountName": { "type": "string", "description": "Account holder's name", "minLength": 8, "maxLength": 64, "example": "Daniel Scorsese" }, "bankName": { "type": "string", "description": "Bank name", "example": "Nombank MFB" }, "bankAccountNumber": { "type": "string", "description": "Bank account number", "example": "9391076543" }, "bankAccountName": { "type": "string", "description": "Bank account holder name", "example": "Nomba/Ifeoluwa Adeboye" }, "currency": { "type": "string", "description": "Currency code", "minLength": 3, "maxLength": 3, "enum": [ "NGN" ], "example": "NGN" }, "callbackUrl": { "type": "string", "description": "Callback url", "format": "url", "example": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7" }, "expired": { "type": "boolean", "description": "Successfully updated", "example": true } }, "required": [ "createdAt", "accountHolderId", "accountRef", "bvn", "accountName", "bankName", "bankAccountName", "bankAccountNumber", "currency", "callbackUrl", "expired" ] }, "RateLimitError": { "type": "object", "description": "Rate-limit error response.", "properties": { "code": { "type": "string", "description": "API error code.", "example": "429" }, "description": { "type": "string", "description": "Additional details about the error.", "example": "Too many requests" } } }, "AuthenticationError": { "type": "object", "description": "Authentication Error response.", "properties": { "code": { "type": "string", "description": "API error code.", "example": "401" }, "description": { "type": "string", "description": "Additional details about the error.", "example": "Unauthorized" } } }, "AuthorizationError": { "type": "object", "description": "Permissions error response.", "properties": { "code": { "type": "string", "description": "API error code.", "example": "403" }, "description": { "type": "string", "description": "Additional details about the error.", "example": "Forbidden" } } }, "RecordNotFoundError": { "type": "object", "description": "Record-Not-Found error response.", "properties": { "code": { "type": "string", "description": "API error code.", "example": "404" }, "description": { "type": "string", "description": "Additional details about the error.", "example": "Record not found" } } }, "RequestError": { "type": "object", "description": "Request Error response.", "properties": { "code": { "type": "string", "description": "API error code.", "example": "400" }, "description": { "type": "string", "description": "Additional details about the error.", "example": "Request failed." } } }, "ServerError": { "type": "object", "description": "Server error response.", "properties": { "code": { "type": "string", "description": "API error code.", "example": "500" }, "description": { "type": "string", "description": "Additional details about the error.", "example": "Server error" } } }, "Processing": { "type": "object", "description": "Processing response.", "properties": { "code": { "type": "string", "description": "Prcessing response.", "example": "202" }, "description": { "type": "string", "description": "Additional details while it is processing.", "example": "Processing" }, "message": { "type": "string", "description": "Processing message", "example": "Processing..." }, "status": { "type": "boolean", "description": "status of the transaction", "example": "false" }, "data": { "type": "object", "properties": { "amount": { "type": "string", "example": "2500" }, "meta": { "type": "object", "properties": { "merchantTxRef": { "type": "string", "example": "ref-2026-02-20-08-51AM" }, "rrn": { "type": "string", "example": "223454678655" } } }, "timeCreated": { "type": "string", "example": "2026-02-20T08:51:02.218356523" }, "type": { "type": "string", "example": "transfer" }, "status": { "type": "string", "example": "Processing" } } } } }, "IssueTokenRequest": { "type": "object", "description": "A structure representing an authentication request.", "properties": { "grant_type": { "type": "string", "description": "The grant type of the authentication.", "enum": [ "client_credentials", "refresh_token" ], "example": "client_credentials" }, "client_id": { "type": "string", "description": "The client's id as obtained from your Nomba dashboard.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "maxLength": 36, "minLength": 36 }, "client_secret": { "type": "string", "description": "The client's secret as obtained from your Nomba dashboard. It is securely generated by the Nomba system", "example": "JFJ8yq3G4+DvjivJMsji0YkZBkkKdSdjifR+TgT9RLM=", "maxLength": 44, "minLength": 44 } }, "required": [ "grant_type", "client_id", "client_secret" ] }, "IssueTokenResponse": { "type": "object", "description": "A structure representing an authentication result.", "properties": { "businessId": { "type": "string", "description": "The accountId of the merchant/business that is connecting to the Nomba system via API", "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "access_token": { "type": "string", "description": "A JWT (Json Web Token) token used to grant access to resources on the Nomba API.", "example": "eyJhbGciOiJIUzI1NiJ9.eyJHOjhmYWM4M2FjLTc2YjAtNDM1Zi1hYTM1LThkOTU3ZGQ5MjdkZCI6Ikc6OGZhYzgzYWMtNzZiMC00MzVmLWFhMzUtOGQ5NTdkZDkyN2RkIiwiUjpURUFNU19PV05FUiI6IlI6VEVBTVNfT1dORVIiLCJFbWFpbDp2aWN0b3JzaG9hZ2FAZ21haWwuY29tIjoiRW1haWw6dmljdG9yc2hvYWdhQGdtYWlsLmNvbSIsImlhdCI6MTY4MTkxODU3OSwic3ViIjoiNWUyNmNmYjAtNTI5Zi00MTdiLWI4ZDItYWJjNDcxZjRjOWRiIiwiZXhwIjoxNjgxOTIyMTc5fQ.lQOsyhR1gajKdzE9IHQEtxhQyUrArctEDZiP9pWVTFY", "maxLength": 600, "minLength": 300 }, "refresh_token": { "type": "string", "description": "A Base64 Encoded String used to refresh an expired access_token", "example": "01h4gdx2tctxfjgacbdwrcvs5d1688473602892", "maxLength": 60, "minLength": 30 }, "expiresAt": { "type": "string", "description": "The date and time this entity was created. This value uses Coordinated Universal Time (UTC) and ISO 8601 format \u2013 `YYYY-MM-DDThh:mm:ssZ`.", "example": "2022-07-08T14:33:00Z" } }, "required": [ "businessId", "access_token", "refresh_token", "expiresAt" ] }, "RefreshTokenRequest": { "type": "object", "description": "A structure representing a refresh token request.", "properties": { "grant_type": { "type": "string", "description": "The grant type of the authentication.", "enum": [ "client_credentials", "refresh_token" ], "example": "refresh_token" }, "refresh_token": { "type": "string", "description": "A Base64 Encoded String used to refresh an expired access_token", "example": "01h4gdx2tctxfjgacbdwrcvs5d1688473602892", "maxLength": 60, "minLength": 30 } }, "required": [ "grant_type", "refresh_token" ] }, "RevokeTokenRequest": { "type": "object", "description": "A structure representing a request to revoke a token.", "properties": { "clientId": { "type": "string", "description": "The client's id as obtained from your Nomba dashboard.", "example": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d", "maxLength": 36, "minLength": 36 }, "access_token": { "type": "string", "description": "The JWT (Json Web Token) token to be revoked", "example": "eyJhbGciOiJIUzI1NiJ9.eyJHOjhmYWM4M2FjLTc2YjAtNDM1Zi1hYTM1LThkOTU3ZGQ5MjdkZCI6Ikc6OGZhYzgzYWMtNzZiMC00MzVmLWFhMzUtOGQ5NTdkZDkyN2RkIiwiUjpURUFNU19PV05FUiI6IlI6VEVBTVNfT1dORVIiLCJFbWFpbDp2aWN0b3JzaG9hZ2FAZ21haWwuY29tIjoiRW1haWw6dmljdG9yc2hvYWdhQGdtYWlsLmNvbSIsImlhdCI6MTY4MTkxODU3OSwic3ViIjoiNWUyNmNmYjAtNTI5Zi00MTdiLWI4ZDItYWJjNDcxZjRjOWRiIiwiZXhwIjoxNjgxOTIyMTc5fQ.lQOsyhR1gajKdzE9IHQEtxhQyUrArctEDZiP9pWVTFY", "maxLength": 600, "minLength": 300 } }, "required": [ "clientId", "access_token" ] }, "RevokeTokenResponse": { "type": "object", "description": "A structure representing a response from an attempt to revoke a token", "properties": { "code": { "type": "string", "description": "Tells if the access_token has been revoked", "example": "00" }, "description": { "type": "string", "description": "Describes the result of the action performed", "example": "Token revoked successfully" } } }, "AccountDetailsResponse": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Creation timestamp", "format": "date-time", "example": "2023-09-04T07:09:06.900Z" }, "accountId": { "type": "string", "description": "Account ID", "minLength": 36, "maxLength": 36, "example": "fc81b80e-e607-4b86-8591-840925191733" }, "accountHolderId": { "type": "string", "description": "Account holder ID", "minLength": 36, "maxLength": 36, "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "accountRef": { "type": "string", "description": "Account reference", "minLength": 16, "maxLength": 64, "example": "1oWbJQQHLyQqqf1SwxjSpudeA21" }, "bvn": { "type": "string", "description": "Bank Verification Number (BVN)", "minLength": 11, "maxLength": 11, "example": "12234412345" }, "status": { "type": "string", "description": "Account status", "enum": [ "ACTIVE", "INACTIVE", "SUSPENDED", "PND", "BLACKLISTED" ], "example": "ACTIVE" }, "type": { "type": "string", "description": "Account type", "enum": [ "virtual", "outlet" ], "example": "virtual" }, "accountName": { "type": "string", "description": "Account holder's name", "minLength": 8, "maxLength": 64, "example": "Daniel Scorsese" }, "currency": { "type": "string", "description": "Currency code", "minLength": 3, "maxLength": 3, "enum": [ "NGN" ], "example": "NGN" }, "banks": { "type": "array", "description": "List of associated bank accounts", "items": { "type": "object", "properties": { "bankAccountNumber": { "type": "string", "description": "Bank account number", "example": "93910" }, "bankName": { "type": "string", "description": "Bank name", "example": "Sterling Bank" }, "bankAccountName": { "type": "string", "description": "Bank account holder name", "example": "Nomba/Ifeoluwa Adeboye" } }, "required": [ "bankAccountNumber", "bankName", "bankAccountName" ] } } }, "required": [ "createdAt", "accountId", "accountHolderId", "accountRef", "bvn", "status", "type", "accountName", "banks", "currency" ] }, "AccountBalanceResponse": { "type": "object", "properties": { "amount": { "type": "string", "description": "Account balance", "example": "281946.0" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Currency code", "enum": [ "NGN" ], "example": "NGN" }, "timeCreated": { "type": "string", "format": "date-time", "description": "Account creation timestamp", "example": "2026-03-08T14:56:59.000Z" } }, "required": [ "amount", "currency", "timeCreated" ] }, "TerminalAssignmentRequest": { "type": "object", "properties": { "serialNumber": { "type": "string", "description": "Serial number", "example": "55555555" }, "terminalLabel": { "type": "string", "description": "Terminal label", "example": "Testing" } }, "required": [ "serialNumber" ] }, "TerminalPaymentRequest": { "type": "object", "description": "Represents a request to initiate a payment on a physical payment terminal.", "properties": { "merchantTxRef": { "type": "string", "description": "The unique identifier for the order associated with the payment.", "example": "55555555" }, "amount": { "type": "number", "description": "The total amount to be charged on the terminal, in the smallest currency unit (e.g., cents, kobo).", "example": "1000" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Currency code based on the ISO4217 standard", "enum": [ "NGN", "USD", "CDF" ], "example": "NGN" } }, "required": [ "merchantTxRef", "amount", "currency" ] }, "TerminalPaymentResponse": { "type": "object", "description": "Represents a response to payment initialization request", "properties": { "paymentId": { "type": "string", "description": "Unique identifier for the payment", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "status": { "type": "string", "description": "Current status of the payment", "enum": [ "pending", "completed", "failed" ], "example": "pending" }, "amount": { "type": "number", "description": "Amount of the payment", "example": 1000 }, "currency": { "type": "string", "description": "Currency code for the payment", "example": "NGN" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the payment was created", "example": "2023-08-30T14:56:59.000Z" } }, "required": [ "paymentId", "status", "amount", "currency", "createdAt" ] }, "TerminalResult": { "type": "object", "properties": { "terminalId": { "type": "string", "description": "Terminal ID", "example": "201124LM" }, "serialNumber": { "type": "string", "description": "Serial number", "example": "55555555" }, "accountId": { "type": "string", "description": "Account ID", "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "parentAccountId": { "type": "string", "description": "Parent account ID", "example": "" }, "merchantName": { "type": "string", "description": "Merchant name", "example": "trident and rees" }, "terminalLabel": { "type": "string", "description": "Terminal label", "example": "Testing" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp", "example": "2020-09-23T10:21:48.789Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp", "example": "2023-09-04T15:23:55.173Z" } }, "required": [ "terminalId", "serialNumber", "accountId", "parentAccountId", "merchantName", "terminalLabel", "createdAt", "updatedAt" ] }, "TerminalListResults": { "type": "object", "properties": { "results": { "type": "array", "description": "Contains list of terminals", "items": { "$ref": "#/components/schemas/TerminalResult" } }, "cursor": { "type": "string", "description": "Cursor for pagination. It will be empty if there is no more page to scroll to", "example": "xchbaVFsjdsbaADddd" } } }, "WalletTransferMetaObject": { "type": "object", "properties": { "merchantTxRef": { "type": "string", "description": "Merchant transaction reference", "example": "3JVW2xJCjj443oannREBuTaXDdji" }, "api_client_id": { "type": "string", "description": "API client ID", "example": "6a7bed88-7c93-4a1c-a445-f88edbca6489" }, "api_account_id": { "type": "string", "description": "API account ID", "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "rrn": { "type": "string", "description": "RRN (Retrieval Reference Number)", "example": "230908151711" } }, "description": "Transaction meta data" }, "WalletTransferRequest": { "type": "object", "description": "A structure representing an object required to post a wallet transfer.", "properties": { "amount": { "type": "number", "format": "double", "description": "The amount to be transferred.", "example": 3500 }, "receiverAccountId": { "type": "string", "format": "uuid", "description": "The receiver's accountId.", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "merchantTxRef": { "type": "string", "description": "Unique reference used to track a transaction from an external process. \n \nThis is an idempotency key and must be unique per transaction.", "example": "UNQ_123abGGhh5546" }, "narration": { "type": "string", "description": "The payment narration", "example": "Testing Payment" } }, "required": [ "amount", "receiverAccountId", "merchantTxRef" ] }, "WalletTransferResult": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "Transfer amount", "example": 5502.0 }, "meta": { "$ref": "#/components/schemas/WalletTransferMetaObject" }, "fee": { "type": "number", "format": "double", "description": "Transfer fee", "example": 50.0 }, "timeCreated": { "type": "string", "format": "date-time", "description": "Creation timestamp", "example": "2023-09-08T14:17:13.634Z" }, "id": { "type": "string", "description": "Transfer ID", "example": "API-P2P-C24AD-a6443bf0-011c-4bc2-b739-4a2e33e2a27b" }, "type": { "type": "string", "description": "Transaction type", "enum": [ "withdrawal", "purchase", "transfer", "p2p", "online_checkout", "qrt_credit", "qrt_debit" ], "example": "p2p" }, "status": { "type": "string", "description": "Transaction status", "enum": [ "SUCCESS", "PENDING_BILLING", "REFUND", "CANCELLED", "PAYMENT_FAILED", "REVERSED_BY_VENDOR" ], "example": "SUCCESS" } }, "required": [ "amount", "meta", "fee", "timeCreated", "id", "type", "status" ], "description": "Transfer data" }, "BankTransactionMetaObject": { "type": "object", "properties": { "billerId": { "type": "string", "description": "Biller ID", "example": "API_FCIR5UQFMYS" }, "terminalActionId": { "type": "string", "description": "Terminal action ID", "example": "" }, "productId": { "type": "string", "description": "Product ID", "example": "p2p" }, "fee": { "type": "number", "format": "double", "description": "Fee", "example": 0.0 }, "type": { "type": "string", "description": "Type", "example": "p2p" }, "transactionId": { "type": "string", "description": "Transaction ID", "example": "API-P2P-84026-d8a4d658-6747-418d-a7e2-37bc6290310d" }, "rrn": { "type": "string", "description": "RRN (Retrieval Reference Number)", "example": "" }, "parentAccountId": { "type": "string", "description": "Parent account ID", "example": "01a10aeb-d989-460a-bbde-9842f2b4320f" }, "terminalLabel": { "type": "string", "description": "Terminal label", "example": "" }, "accountId": { "type": "string", "description": "Account ID", "example": "890022ce-bae0-45c1-9b9d-ee7872e6ca27" }, "merchantTxRef": { "type": "string", "description": "Merchant transaction reference", "example": "" }, "transactionAmount": { "type": "number", "format": "double", "description": "Transaction amount", "example": 7000.0 }, "mCollectionsId": { "type": "string", "description": "MCollections ID", "example": "" } } }, "BankTransactionResult": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "Amount", "example": 7000.0 }, "currency": { "type": "string", "description": "Currency", "enum": [ "NGN" ], "example": "NGN" }, "meta": { "$ref": "#/components/schemas/BankTransactionMetaObject" }, "status": { "type": "string", "description": "Status", "enum": [ "SUCCESS", "PENDING_BILLING", "REFUND", "CANCELLED", "PAYMENT_FAILED", "REVERSED_BY_VENDOR" ], "example": "SUCCESS" }, "timeUpdated": { "type": "string", "format": "date-time", "description": "Updated timestamp", "example": "2023-09-08T19:05:21.000Z" }, "walletBalance": { "type": "number", "format": "double", "description": "The account balance", "example": 285951.0 }, "transactionType": { "type": "string", "description": "Transaction type", "enum": [ "CREDIT", "DEBIT" ], "example": "DEBIT" } }, "required": [ "amount", "currency", "meta", "status", "timeUpdated", "walletBalance", "transactionType" ] }, "BankTransactionListResults": { "type": "object", "properties": { "results": { "type": "array", "description": "Contains list of credit/debit transactions", "items": { "$ref": "#/components/schemas/BankTransactionResult" } }, "cursor": { "type": "string", "description": "Cursor for pagination. It will be empty if there is no more page to scroll to", "example": "xchbaVFsjdsbaADddd" } } }, "FilterTransactionRequest": { "type": "object", "properties": { "transactionRef": { "type": "string", "description": "Transaction ID/Reference", "example": "POS-WITHDRAW-DFC05-693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea" }, "status": { "type": "string", "description": "Transaction status", "enum": [ "NEW", "PENDING_PAYMENT", "PAYMENT_SUCCESSFUL", "PAYMENT_FAILED", "PENDING_BILLING", "SUCCESS", "REFUND" ], "example": "SUCCESS" }, "source": { "type": "string", "description": "Transaction source", "enum": [ "api", "pos", "web", "android_app", "ios_app" ], "example": "pos" }, "type": { "type": "string", "description": "Transaction type", "enum": [ "withdrawal", "purchase", "transfer", "p2p", "online_checkout", "qrt_credit", "qrt_debit" ], "example": "withdrawal" }, "terminalId": { "type": "string", "description": "Terminal ID", "example": "2KUD4AKB" }, "rrn": { "type": "string", "description": "RRN (Retrieval Reference Number)", "example": "230908202632" }, "merchantTxRef": { "type": "string", "description": "Merchant transaction reference", "example": "c90d-4b25-ad0f" }, "orderReference": { "type": "string", "description": "Online checkout order reference", "example": "693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea" }, "orderId": { "type": "string", "description": "Online checkout order id", "example": "285e4ad2-665f-453b-8795-e854cab5757b" } } }, "TransactionResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID", "example": "POS-WITHDRAW-DFC05-693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea" }, "status": { "type": "string", "description": "Transaction status. \n `SUCCESS` means the transaction was successful. \n `REFUND` means the transaction failed and has been refunded to your account. \n `PENDING_BILLING`, `CANCELLED`, `PAYMENT_FAILED`, and `REVERSED_BY_VENDOR` mean the transaction is pending.", "enum": [ "SUCCESS", "PENDING_BILLING", "REFUND", "CANCELLED", "PAYMENT_FAILED", "REVERSED_BY_VENDOR" ], "example": "SUCCESS" }, "amount": { "type": "number", "format": "double", "description": "Transaction amount", "example": 4000.0 }, "fixedCharge": { "type": "number", "format": "double", "description": "Fixed charge", "example": 0.0 }, "source": { "type": "string", "description": "Transaction source", "enum": [ "api", "pos", "web", "android_app", "ios_app" ], "example": "pos" }, "type": { "type": "string", "description": "Transaction type", "enum": [ "withdrawal", "purchase", "transfer", "p2p", "online_checkout", "qrt_credit", "qrt_debit" ], "example": "withdrawal" }, "gatewayMessage": { "type": "string", "description": "Gateway message", "example": "SUCCESS" }, "customerBillerId": { "type": "string", "description": "Customer biller ID", "example": "539983 **** **** 5118" }, "timeCreated": { "type": "string", "format": "date-time", "description": "Creation timestamp", "example": "2026-03-08T19:26:34.657000Z" }, "posTid": { "type": "string", "description": "POS terminal ID", "example": "2KUD4AKB" }, "terminalId": { "type": "string", "description": "Terminal ID", "example": "2KUD4AKB" }, "providerTerminalId": { "type": "string", "description": "Provider terminal ID", "example": "2KUD4AKB" }, "rrn": { "type": "string", "description": "RRN (Retrieval Reference Number)", "example": "230908202632" }, "posSerialNumber": { "type": "string", "description": "POS serial number", "example": "91230309116826" }, "posTerminalLabel": { "type": "string", "description": "POS terminal label", "example": "KEB MUSA ABUBAKAR" }, "stan": { "type": "string", "description": "STAN (System Trace Audit Number)", "example": "556734" }, "paymentVendorReference": { "type": "string", "description": "Payment vendor reference", "example": "2KUD4AKB230908202632" }, "userId": { "type": "string", "description": "User ID", "example": "dfc05ca1-4e75-41dd-8e41-2d362d565893" }, "posRrn": { "type": "string", "description": "POS RRN (Retrieval Reference Number)", "example": "230908202632" }, "merchantTxRef": { "type": "string", "description": "Merchant transaction reference", "example": "c90d-4b25-ad0f" } }, "required": [ "id", "status", "amount", "source", "type", "gatewayMessage", "timeCreated" ] }, "TransactionListResults": { "type": "object", "properties": { "results": { "type": "array", "description": "Contains list of transactions", "items": { "$ref": "#/components/schemas/TransactionResult" } }, "cursor": { "type": "string", "description": "Cursor for pagination. It will be empty if there is no more page to scroll to", "example": "xchbaVFsjdsbaADddd" } } }, "VirtualAccountListResults": { "type": "object", "properties": { "results": { "type": "array", "description": "Contains list of virtual accounts", "items": { "$ref": "#/components/schemas/VirtualAccountObject" } }, "cursor": { "type": "string", "description": "Cursor for pagination. It will be empty if there is no more page to scroll to", "example": "xchbaVFsjdsbaADddd" } } }, "AccountAccessRequest": { "type": "object", "description": "A structure representing an account access request", "properties": { "grantType": { "type": "string", "description": "The action to perform on the access", "enum": [ "allow", "deny" ], "example": "allow" }, "clientId": { "type": "string", "description": "The client to grant/deny access to the account", "example": "09132aea-367f-447d-9d9b-46af5a319318" }, "role": { "type": "string", "description": "The role to assume within the account", "enum": [ "ACCOUNT_WRITER", "ACCOUNT_READER" ], "default": "ACCOUNT_WRITER", "example": "ACCOUNT_WRITER" } }, "required": [ "grantType", "clientId", "role" ] }, "GenericObjectResult": { "type": "object", "description": "A structure representing a bank account lookup result", "properties": { "message": { "type": "string", "description": "Action has been performed successfully" }, "data": { "type": "object", "description": "The data object attributed to the action that has been performed", "example": { "name": "M.A Animashaun", "age": 30, "city": "Example City" } } }, "required": [ "message" ] }, "DataPlanList": { "type": "object", "properties": { "amount": { "type": "integer", "format": "int64" }, "plan": { "type": "string", "example": "40GB -> 30Days (N15,000)" } } }, "DiscoList": { "type": "object", "properties": { "id": { "type": "string", "example": "jed" }, "name": { "type": "string", "example": "Jos Electric (JEDC)" } } }, "BettingProvider": { "type": "object", "properties": { "lookup_id": { "type": "string", "example": "BET9JA" }, "amount": { "type": "string", "example": "" }, "name": { "type": "string", "example": "BET9JA" }, "biller_id": { "type": "string", "example": "bet9ja" }, "id": { "type": "string", "example": "bet9ja" } }, "required": [ "name", "id" ] }, "BettingProvidersList": { "type": "array", "description": "List of all betting providers", "items": { "$ref": "#/components/schemas/BettingProvider" } }, "ElectricityVendingRequest": { "type": "object", "properties": { "disco": { "type": "string", "example": "jed" }, "merchantTxRef": { "type": "string", "description": "This is an idempotency key and must be unique per transaction.", "example": "12345" }, "payerName": { "type": "string", "example": "John Doe" }, "amount": { "type": "integer", "example": 1000 }, "customerId": { "type": "string", "example": "customer123" }, "meterType": { "type": "string", "example": "prepaid" } } }, "ElectricityVendingResponse": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "The value (in digits) of this transaction", "example": 2000 }, "timeCreated": { "type": "string", "description": "The Date and Time of transaction creation", "format": "date-time", "example": "2026-02-06T07:09:06.900Z" }, "type": { "type": "string", "description": "The classification for this type of transaction", "example": "phcn" }, "meta": { "type": "object", "description": "Extra information about this transaction", "example": { "merchantTxRef": "test1116", "phcnCustomerAddress": "52, Ajose Street", "phcnVendUnits": "23.5", "phcnVendToken": "12345678909876543212", "meterName": "John Doe", "meterType": "PREPAID", "rrn": "240626232937", "api_client_id": "123456-9100-4e66-93e1-7f6da894ef89", "api_account_id": "0167288-d989-460a-bbde-9842f2b4320f" } }, "status": { "type": "string", "description": "The system status of this transction", "example": "SUCCESS" }, "id": { "type": "string", "description": "The transaction Id", "example": "SUCCESS" }, "fee": { "type": "string", "description": "The associated transaction fee", "example": "0.0" } }, "required": [ "amount", "timeCreated", "type", "status", "meta", "id" ] }, "CableTvSubscriptionRequest": { "type": "object", "properties": { "cableTvType": { "type": "string", "example": "dstv" }, "merchantTxRef": { "type": "string", "description": "This is an idempotency key and must be unique per transaction.", "example": "12345" }, "payerName": { "type": "string", "example": "John Doe" }, "amount": { "type": "integer", "example": 1000 }, "customerId": { "type": "string", "example": "customer123" } } }, "CableTvSubscriptionResponse": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "The value (in digits) of this transaction", "example": 2000 }, "timeCreated": { "type": "string", "description": "The Date and Time of transaction creation", "format": "date-time", "example": "2023-09-04T07:09:06.900Z" }, "type": { "type": "string", "description": "The classification for this type of transaction", "example": "dstv" }, "meta": { "type": "object", "description": "Extra information about this transaction", "example": { "merchantTxRef": "test1116", "rrn": "240626232937", "api_client_id": "123456-9100-4e66-93e1-7f6da894ef89", "api_account_id": "0167288-d989-460a-bbde-9842f2b4320f" } }, "status": { "type": "string", "description": "The system status of this transction", "example": "SUCCESS" }, "id": { "type": "string", "description": "The transaction Id", "example": "SUCCESS" }, "fee": { "type": "string", "description": "The associated transaction fee", "example": "0.0" } }, "required": [ "amount", "timeCreated", "type", "status", "meta", "id" ] }, "BettingVendingRequest": { "type": "object", "properties": { "bettingProvider": { "type": "string", "example": "bet9ja" }, "merchantTxRef": { "type": "string", "description": "This is an idempotency key and must be unique per transaction.", "example": "12345" }, "phoneNumber": { "type": "string", "example": "09012345678" }, "payerName": { "type": "string", "example": "John Doe" }, "amount": { "type": "integer", "example": 1000 }, "customerId": { "type": "string", "example": "customer123" } } }, "BettingVendingResponse": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "description": "The value (in digits) of this transaction", "example": 2000 }, "timeCreated": { "type": "string", "description": "The Date and Time of transaction creation", "format": "date-time", "example": "2023-09-04T07:09:06.900Z" }, "type": { "type": "string", "description": "The classification for this type of transaction", "example": "phcn" }, "meta": { "type": "object", "description": "Extra information about this transaction", "example": { "merchantTxRef": "test1116", "rrn": "240626232937", "api_client_id": "123456-9100-4e66-93e1-7f6da894ef89", "api_account_id": "0167288-d989-460a-bbde-9842f2b4320f" } }, "status": { "type": "string", "description": "The system status of this transaction", "example": "SUCCESS" }, "id": { "type": "string", "description": "The transaction Id", "example": "SUCCESS" }, "fee": { "type": "string", "description": "The associated transaction fee", "example": "0.0" } }, "required": [ "amount", "timeCreated", "type", "status", "meta", "id" ] }, "PageResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "$ref": "#/components/schemas/DirectDebitMandateData" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "boolean" } } }, "DirectDebitMandateData": { "type": "object", "properties": { "status": { "type": "string" }, "customerAccountNumber": { "type": "string" }, "customerAccountName": { "type": "string" }, "bankCode": { "type": "string" }, "amount": { "type": "number" }, "customerName": { "type": "string" }, "customerAddress": { "type": "string" }, "customerEmail": { "type": "string" }, "customerPhoneNumber": { "type": "string" }, "merchantReference": { "type": "string" }, "frequency": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "mandateAdviceStatus": { "type": "string" }, "mandateId": { "type": "string" } } }, "UpdateMandateStatusRequest": { "type": "object", "properties": { "mandateId": { "type": "string", "description": "Unique identifier of the mandate" }, "status": { "type": "string", "enum": [ "SUSPEND", "ACTIVE", "DELETE" ], "description": "New status of the mandate" } }, "required": [ "mandateId", "status" ] }, "UpdateMandateStatusResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "SUCCESS" }, "data": { "type": "object", "properties": { "mandateId": { "type": "string", "example": "c93e1e1b-85f5-461e-8b9b-74ee091d4aa4" }, "mandateStatus": { "type": "string", "example": "Advise not sent" } } }, "message": { "type": "string", "example": "SUCCESS" }, "status": { "type": "boolean", "example": true } }, "required": [ "code", "description", "data", "message", "status" ] }, "DebitMandateRequest": { "type": "object", "properties": { "mandateId": { "type": "string", "description": "Unique identifier of the mandate to debit" }, "amount": { "type": "string", "description": "Amount to be debited" } }, "required": [ "mandateId", "amount" ] }, "DebitMandateResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "SUCCESS" }, "data": { "type": "object", "properties": { "mandateId": { "type": "string", "example": "89b0efc0-dde5-49e2-8bde-5523ae081c43" }, "status": { "type": "string", "example": "SUCCESS" }, "amount": { "type": "string", "example": "110.00" }, "message": { "type": "string", "example": "Approved or completed successfully" } } }, "message": { "type": "string", "example": "SUCCESS" }, "status": { "type": "boolean", "example": true } }, "required": [ "code", "description", "data", "message", "status" ] }, "GetMandateStatusResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "SUCCESS" }, "data": { "type": "object", "properties": { "customerAccountName": { "type": "string", "example": "Kolapo Ojo" }, "mandateId": { "type": "string", "example": "c93e1e1b-85f5-461e-8b9b-74ee091d4aa4" }, "customerAccountNumber": { "type": "string", "example": "0134914434" }, "mandateStatus": { "type": "string", "example": "Active" }, "rejectionComment": { "type": "string", "example": "Expired e-mandate" }, "mandateAdviceStatus": { "type": "string", "example": "Advise not sent" } }, "required": [ "customerAccountName", "mandateId", "customerAccountNumber", "mandateStatus" ] }, "message": { "type": "string", "example": "SUCCESS" }, "status": { "type": "boolean", "example": true } }, "required": [ "code", "description", "data", "message", "status" ] }, "GetMandateByIdResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "00" }, "description": { "type": "string", "example": "SUCCESS" }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "ACTIVE" }, "customerAccountNumber": { "type": "string", "example": "014453434" }, "customerAccountName": { "type": "string", "example": "Kolapo Ojo" }, "bankCode": { "type": "string", "example": "057" }, "amount": { "type": "number", "format": "double", "example": 100.0 }, "customerName": { "type": "string", "example": "Kolapo Ojo" }, "customerAddress": { "type": "string", "example": "maryland Ikeja computer village" }, "customerEmail": { "type": "string", "example": "kolapo@gmail.com" }, "customerPhoneNumber": { "type": "string", "example": "080456414423" }, "merchantReference": { "type": "string", "example": "12003074001" }, "frequency": { "type": "string", "example": "VARIABLE" }, "startDate": { "type": "array", "items": { "type": "integer" }, "example": [ 2025, 8, 13, 15, 30 ] }, "endDate": { "type": "array", "items": { "type": "integer" }, "example": [ 2025, 8, 30, 10, 40 ] }, "mandateAdviceStatus": { "type": "string", "example": null }, "mandateId": { "type": "string", "example": "e50b7835-502c-4cfe-8828-47657633d7a2" } }, "required": [ "status", "customerAccountNumber", "customerAccountName", "bankCode", "amount", "customerName", "merchantReference", "frequency", "startDate", "endDate", "mandateId" ] }, "message": { "type": "string", "example": "SUCCESS" }, "status": { "type": "boolean", "example": true } }, "required": [ "code", "description", "data", "message", "status" ] }, "CreateMandateRequest": { "type": "object", "properties": { "customerAccountNumber": { "type": "string", "example": "0174534423" }, "bankCode": { "type": "string", "example": "101" }, "customerName": { "type": "string", "example": "Kolapo Ojo" }, "customerAddress": { "type": "string", "example": "maryland Ikeja computer village" }, "customerAccountName": { "type": "string", "example": "Kolapo Ojo" }, "amount": { "type": "number", "format": "double", "example": 100 }, "frequency": { "type": "string", "enum": [ "VARIABLE", "WEEKLY", "EVERY_TWO_WEEKS", "MONTHLY", "EVERY_TWO_MONTHS", "EVERY_THREE_MONTHS", "EVERY_FOUR_MONTHS", "EVERY_FIVE_MONTHS", "EVERY_SIX_MONTHS", "EVERY_SEVEN_MONTHS", "EVERY_EIGHT_MONTHS", "EVERY_NINE_MONTHS", "EVERY_TEN_MONTHS", "EVERY_ELEVEN_MONTHS", "EVERY_TWELVE_MONTHS" ], "example": "WEEKLY" }, "narration": { "type": "string", "example": "test e mandate response" }, "customerPhoneNumber": { "type": "string", "example": "0807882343" }, "merchantReference": { "type": "string", "description": "A NUMERIC string (0-9) used to track a transaction. It must be unique per transaction.", "example": "120030740017" }, "startDate": { "type": "string", "format": "date-time", "example": "2025-08-29T14:58" }, "endDate": { "type": "string", "format": "date-time", "example": "2025-08-30T10:40" }, "customerEmail": { "type": "string", "example": "kolapo@gmail.com" }, "startImmediately": { "type": "boolean", "example": true } }, "required": [ "customerAccountNumber", "bankCode", "customerName", "customerAccountName", "amount", "frequency", "merchantReference", "startDate", "endDate", "customerEmail" ] }, "CreateMandateResponse": { "type": "object", "properties": { "responseMessage": { "type": "string", "example": "Success" }, "responseCode": { "type": "string", "example": "00" }, "data": { "type": "object", "properties": { "mandateId": { "type": "string", "example": "e50b7835-502c-4cfe-9893-47657633d7a2" }, "merchantReference": { "type": "string", "example": "12003074001" }, "phoneNumber": { "type": "string", "example": "08073345562" }, "description": { "type": "string", "example": "Welcome to NIBSS e-mandate authentication service, a seamless and convenient authentication experience. Kindly proceed with a token payment of N50.00..." } }, "required": [ "mandateId", "merchantReference", "phoneNumber", "description" ] } }, "required": [ "responseMessage", "responseCode", "data" ] }, "CancelOrderRequest": { "type": "object", "description": "The request payload to cancel a checkout order", "properties": { "orderReference": { "type": "string", "description": "The unique reference of the checkout order to cancel", "example": "OD-69923-2e102708-ee34-4a29-b713-a826ca928a12" } }, "required": [ "orderReference" ] }, "CancelOrderResponse": { "type": "object", "description": "The response object for a cancel order operation", "properties": { "success": { "type": "boolean", "description": "Indicates whether the cancellation was successful", "example": true }, "message": { "type": "string", "description": "A message describing the result of the cancellation", "example": "Order cancelled successfully" } }, "required": [ "success", "message" ] } }, "securitySchemes": { "BearerAuth": { "description": "Nomba authenticates API calls with [OAuth2 HTTP bearer tokens](http://tools.ietf.org/html/rfc6750). There are two methods of authentication; [Client-Credentials method](https://www.rfc-editor.org/rfc/rfc6749) and [PKCE (Proof Key for Code Exchange)](https://www.rfc-editor.org/rfc/rfc7636) method. In each of the methods, You will get an `ACCESS_TOKEN`. You need to use an `\"Authorization\"` HTTP header to provide your `ACCESS_TOKEN`. For example: `Authorization: {ACCESS_TOKEN}`.", "scheme": "bearer", "type": "http", "bearerFormat": "JWT" } } } }