--- swagger: "2.0" info: version: 2.3.0 title: Wallet description: "<!-- SEE BOTTOM FOR MARKDOWN SYNTAX -->\n\n## Nedbank : API Marketplace MobiMoney Wallet API\n\n## Introduction\n\nThis is a scalable REST endpoint for all API Marketplace Wallet, Escrow and Payments related functionality.\n\n## General Usage\nThis API is publicly accessible. It expects that all calls are as a result of a previously authenticated user or system coming through the API Marketplace. Calls must include an "authorization" header with a bearer token\nThe following are the standards followed by this REST API:\n\n### Terminology\n\n1. A Resource is an object or representation of something, which has some associated data with it and there can be set of methods to operate on it.\n E.g. Animals, schools and employees are resources and delete, add, update are the operations to be performed on these resources.\n1. Collections are a set of resources, e.g wallets is the collection of Wallet resources.\n1. URL (Uniform Resource Locator) is a path through which a resource can be located and some actions can be performed on it.\n\n### URL Standards\n\nThe URL will only contain resources(nouns) not actions or verbs. The names should make sense from the perspective of the API consumer. \nAlthough the backend microservice models may map neatly to resources exposed on the orchestrated API, it isn't necessarily a one-to-one mapping. \nThe key here is to not leak irrelevant implementation details out to the API.\n\nInput will look as much like output as possible.\n\nPath segments that are more than one word will be split with a hyphen. E.g. /xxx/hello-world/\n\nThe resource will always be plural in the API endpoint and if you want to access one instance of the resource, you can always pass the id in the URL. E.g.:\n\n\nGET path /wallets/ would get the list of all wallets\n\nGET path /wallets/34 would get the detail of wallet 34\n\nDELETE path /wallets/34 would delete wallet 34\nIn other use cases, if we have resources under a resource, e.g Employees of a Company, then the sample API endpoints would be:\n\nGET /wallets/3/reservations/ would get the list of all reservations from wallet 3\n\nGET /wallets/3/reservations/45 would get the details of employee 45, which belongs to wallet 3\n\nDELETE /wallets/3/reservations/45 would delete reservation 45, which belongs to wallet 3\n\nPOST /wallets would create a new wallet and return the details of the new wallet created\n\n### HTTP Methods\n\n1. GET - get a resource.\n1. POST - create a new resource.\n1. PUT - Update an existing resource in its entirety.\n1. DELETE - Delete a resource.\n1. PATCH - Similar to PUT but only update the fields provided. All others are left as-is\n\n### Status Codes\n\nWhen the client raises a request to the server through an API, the client will get feedback on whether it failed, passed or the request was invalid. \nThe server will always return the right status code. The following are the important categories of HTTP codes:\n\n#### 2xx (Success category)\n\nThese status codes represent that the requested action was received and successfully processed by the server.\n\n1. 200 Ok The standard HTTP response representing success for GET, PUT or POST that returns a response body.\n1. 201 Created where a POST results in a resource being created but is not returned in the response body.\n1. 204 No Content represents the request is successfully processed, but has not returned any content nor created anything.\nDELETE can be a good example of this.\nThe API DELETE /wallets/43/reservations/2 will delete the reservation 2 and in return we do not need any data in the response body of the API, as we explicitly asked the system to delete. \nIf there is any error, like if reservation 2 does not exist in the database, then the response code would be not be of 2xx Success Category but around 4xx Client Error category.\n\n#### 3xx (Redirection Category)\n\n304 Not Modified indicates that the client has the response already in its cache. And hence there is no need to transfer the same data again.\n\n#### 4xx (Client Error Category)\n\nThese status codes represent that the client has raised a faulty request.\n1. 400 Bad Request indicates that the request by the client was not processed, as the server could not understand what the client is asking for.\n1. 401 Unauthorized indicates that the client is not allowed to access resources, and should re-request with the required credentials.\n1. 403 Forbidden indicates that the request is valid and the client is authenticated, but the client is not allowed access the page or resource for any reason. E.g sometimes the authorized client is not allowed to access the directory on the server.\n1. 404 Not Found indicates that the requested resource is not available now or does not exist\n\n#### 5xx (Server Error Category)\n\n500 Internal Server Error indicates that the request is valid, but the server has failed to process it for some system related reason.\n503 Service Unavailable indicates that the server is down or unavailable to receive and process the request. Mostly if the server is undergoing maintenance.\n\n\n### Idempotency\n\nAll API's that can result in state changes on the backend services will have a ExternalUniqueId in the JSON payload. \nThis id allows the backend system to return with an error if the transaction is a duplicate. It is advised that the ExternalUniqueId string is a combination of data guaranteed to be unique\nand associated to the transaction so that its impossible for duplicates (e.g. to charge for eCommerce order number 12345, make the uniqueId order-pay-12345).\n\n Where this cannot be done, clients can pass a UUID/GUID as the ExternalUniqueId but this is not as foolproof as application bugs could result in a call being done twice and each time a new unique Id is passed by the client.\n\n\n\n## Wallet, Escrow & Payments Information Model\n\n### Wallet\n\nA wallet represents a digital store of value in ZAR. A wallet has 2 balances associated to it:\n1. Current balance which is the total that is stored in the wallet\n1. Available balance which is the total balance less any reservations. Reservations occur when a wallet intends to pay for something but the payment has not taken place yet. \nThe system ensures that wallets cannot try and pay for something with funds that have already been earmarked (reserved) for another transactions. Reservations can be committed or released or expire.\nWhen a reservation is committed then the current balance would come down to the available balance (assuming that was the only reservation).\n\n\n### Transaction History\n\nThe transaction history is an entry in the ledger that impacted the current balance of a wallet. This stores all of the associated information relating to the debit/credit.\n\n### P2P Transfer\n\nA transfer results in a debit/credit combination across 2 wallets. This is the simplest action that can be taken.\n\n\n\n<!--\nMarkdown syntax: https://learn.getgrav.org/content/markdown\n\nBasics:\n# h1 Heading\n## h2 Heading\n### h3 Heading\n#### h4 Heading\n##### h5 Heading\n###### h6 Heading\n\n*** Horizontal rule\n\n**This will display in bold**\n\n_This will be in italics_\n\nOrdered list auto numbered:\n\n1. item\n1. item\n1. item\n\nIn this example, `<section></section>` should be wrapped as **code**.\n\n```\nA block of code\n```\n\nA Link: [Assemble](http://assemble.io)\n\n-->\n" contact: [] x-ibm-name: wallet name: "" basePath: /nb-wallet schemes: - https consumes: - application/json produces: - application/json - cc309236 paths: /wallets: post: description: |- This API will create a new wallet, which contains latest balance, choosen unit type i.e. 'USD', 'ZAR', wallet type, etc. If a wallet already exists then the customer will be asked to provide consent to the TPP to access it by entering their MobiMoney PIN. If a wallet does not exist then the customer will be asked by to agree to wallet creation and set a PIN and allow TPP consent to access the wallet. Can be used by TPP. summary: createWalle operationId: walletsPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: body in: body required: false description: "" schema: $ref: '#/definitions/CreateWalletRequest' responses: 200: description: OK schema: $ref: '#/definitions/Wallet' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' /wallets/{walletId}: get: description: Get a wallet by providing the unique walletId. Can be used by untrusted TPP. summary: getWallet operationId: walletsByWalletIdGet tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" responses: 200: description: OK schema: $ref: '#/definitions/Wallet' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - PSUOAuth2Security: - wallet - openid X-IBM-Client-Secret: [] X-IBM-Client-Id: [] /callbacks/{callbackId}: get: description: Used for polling by third parties who cannot accept HTTP callbacks (webhooks) summary: getCallbackResult operationId: getCallbackResult tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: callbackId in: path required: true type: string description: "" responses: 200: description: OK schema: $ref: '#/definitions/CallbackResponse' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - X-IBM-Client-Secret: [] X-IBM-Client-Id: [] TPPOAuth2Security: - tpp_client_credential /configurations/terms-and-conditions: get: description: Get terms and conditions to show a user of MobiMoney. summary: getTermsAndConditions operationId: configurationsTermsAndConditionsGet tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - text/plain parameters: [] responses: 200: description: OK schema: type: string headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' /configurations/marketing-info: get: description: Get marketing info about MobiMoney. summary: getMarketingInfo tags: - Wallet operationId: configurationsMarketingInfoGet x-swagger-router-controller: Wallet deprecated: false produces: - text/plain parameters: [] responses: 200: description: OK schema: type: string headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' /configuration/catalogue: get: summary: Query Value Added Services Catalogue description: Query Catalogue operationId: getCatalogue tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: categoryID in: query description: Identifier of the category to retrieve. required: false type: array items: type: string collectionFormat: multi - in: header name: x-fapi-interaction-id type: string required: false description: An RFC4122 UID used as a correlation id. responses: 200: description: 'OK: The result of the catalogue query' headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/CatalogueQueryResponse' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 429: description: Too Many Requests 500: description: Internal Server Error /configuration/income-types: get: summary: Reference Data for income types description: Source of Income List operationId: getIncomeTypesList tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - in: header name: x-fapi-interaction-id type: string required: false description: An RFC4122 UID used as a correlation id. responses: 200: description: 'OK: The result of the source of income' headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/IncomeTypesResponse' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 429: description: Too Many Requests 500: description: Internal Server Error /configuration/industry-types: get: summary: Reference Data for industry types description: Indutry Types List operationId: getIndustryTypesList tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - in: header name: x-fapi-interaction-id type: string required: false description: An RFC4122 UID used as a correlation id. responses: 200: description: 'OK: The result of the industry types list' headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/IndustryTypesResponse' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 429: description: Too Many Requests 500: description: Internal Server Error /configuration/occupation-types: get: summary: Reference Data for occupation description: Occuptation List operationId: getOccupationTypesList tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - in: header name: x-fapi-interaction-id type: string required: false description: An RFC4122 UID used as a correlation id. responses: 200: description: 'OK: The result of the occupation list' headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/OccupationTypesResponse' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 429: description: Too Many Requests 500: description: Internal Server Error /wallets/{walletId}/identity/customer/approve: post: description: "" summary: customer approval (based on ussd/web auth) operationId: customerApprove tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json responses: 200: description: A successful response. headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/CustomerApproveResponse' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 429: description: Too Many Requests 500: description: Internal Server Error parameters: - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/Authorization-Param' - $ref: '#/parameters/x-nb-subscription-id' - name: walletId in: path required: true type: string description: "" - name: body in: body required: true schema: $ref: '#/definitions/CustomerApproveRequest' get: description: "" summary: "" operationId: getCustomerApprovalStatus tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/Authorization-Param' - $ref: '#/parameters/x-nb-subscription-id' - $ref: '#/parameters/x-ibm-client-id' - $ref: '#/parameters/x-ibm-client-secret' - in: header name: grant_type required: true type: string - in: header name: scope required: true type: string - in: header name: redirect_uri required: true type: string - in: header name: callback-id required: true type: string - in: header name: wallet-id required: true type: string - name: walletId in: path required: true type: string description: "" responses: 200: description: Success headers: interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/CreateHeavyTokenResp' 400: description: Bad Request 401: description: Unauthorized 403: description: Forbidden 429: description: Too Many Requests 500: description: Internal Server Error /wallets/{walletId}/atm-withdrawals: post: description: |- This API will initiate an ATM withdrawal from this wallet. Can be used by TPP and in this case the customer will be asked out of band to enter MobiMoney PIN to authorise the ATM withdrawal. summary: doAtmOut operationId: walletsAtmWithdrawalsByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: $ref: '#/definitions/AtmOutRequest' responses: 200: description: OK schema: $ref: '#/definitions/AtmOutResponse' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - PSUOAuth2Security: - wallet - openid X-IBM-Client-Secret: [] X-IBM-Client-Id: [] /wallets/{walletId}/efts-out: post: description: |- This API will initiate an EFT out to a bank account. Can be used by TPP and in this case the customer will be asked out of band to enter MobiMoney PIN to authorise the transfer. summary: doEftOut operationId: walletsEftsOutByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: $ref: '#/definitions/EftOutRequest' responses: 200: description: OK schema: $ref: '#/definitions/EftOutResponse' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - PSUOAuth2Security: - wallet - openid X-IBM-Client-Secret: [] X-IBM-Client-Id: [] /wallets/{walletId}/p2p-transfers: post: description: "This API will do a transfer from this wallet to another. Can be used by\n TPP and in this case the customer will be asked out of band \n to enter MobiMoney PIN to authorise the transfer." summary: doPeer2PeerTransfer operationId: walletsP2pTransfersByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: $ref: '#/definitions/Peer2PeerRequest' responses: 200: description: OK schema: $ref: '#/definitions/Peer2PeerResponse' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - PSUOAuth2Security: - wallet - openid X-IBM-Client-Secret: [] X-IBM-Client-Id: [] /wallets/{walletId}/qrcodes: get: description: Get the details of a QRCode summary: getQrCodeInfo operationId: qrcodesGet tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: qrCode in: query required: false type: string description: The string encoded in the QRCode responses: 200: description: OK schema: $ref: '#/definitions/QrCodeInfo' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' /wallets/{walletId}/qrcode-payments: post: description: This API will initiate a payment out to a the destination QRCode summary: doQrCodePayment operationId: walletsQrcodePaymentsByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: $ref: '#/definitions/QrCodePaymentRequest' responses: 200: description: OK schema: $ref: '#/definitions/QrCodePaymentResponse' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - X-IBM-Client-Secret: [] X-IBM-Client-Id: [] PSUOAuth2Security: - wallet - openid /wallets/{walletId}/vas-purchases: post: description: |- This API will charge the wallet and provision the VAS. Can be used by TPP and in this case the customer will be asked out of band to enter MobiMoney PIN to authorise the purchase. summary: purchaseVas operationId: walletsVasPurchasesByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: $ref: '#/definitions/PurchaseVasRequest' responses: 200: description: OK schema: $ref: '#/definitions/PurchaseVasResponse' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - X-IBM-Client-Secret: [] X-IBM-Client-Id: [] PSUOAuth2Security: - wallet - openid /wallets/{walletId}/reservations: get: description: Get a wallets reservations summary: getReservations operationId: walletsReservationsByWalletIdGet tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" responses: 200: description: OK schema: type: array items: $ref: '#/definitions/Reservation' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - X-IBM-Client-Id: [] X-IBM-Client-Secret: [] PSUOAuth2Security: - wallet - openid post: description: This API will place a hold on the requested amount (if available) for the requested period of time summary: reserve operationId: walletsReservationsByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: $ref: '#/definitions/CreateReservationRequest' responses: 200: description: OK schema: $ref: '#/definitions/ReservationResponse' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - X-IBM-Client-Secret: [] X-IBM-Client-Id: [] PSUOAuth2Security: - wallet - openid /wallets/{walletId}/reservations/{reservationId}: delete: description: Deletes the reservation summary: deleteReservation operationId: walletsReservationsByWalletIdAndReservationIdDelete tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: reservationId in: path required: true type: string description: "" - name: walletId in: path required: true type: string description: "" responses: 200: description: OK headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - X-IBM-Client-Secret: [] X-IBM-Client-Id: [] PSUOAuth2Security: - wallet - openid /wallets/{walletId}/impersonal-transactions: post: description: This API will debit/credit the wallet and debit/credit an impersonal account. summary: doImpersonalTransaction operationId: walletsImpersonalTransactionsByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: $ref: '#/definitions/ImpersonalRequest' responses: 200: description: OK schema: $ref: '#/definitions/ImpersonalResponse' headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - X-IBM-Client-Secret: [] X-IBM-Client-Id: [] PSUOAuth2Security: - wallet - openid /wallets/{walletId}/reversals/{transactionId}: post: description: This API will do reverse transaction of given transactionId summary: reverseTransaction operationId: reverseTransaction tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: transactionId in: path required: true type: string description: "" - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: type: object responses: 200: description: OK headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' security: - PSUOAuth2Security: - wallet - openid X-IBM-Client-Secret: [] X-IBM-Client-Id: [] /wallets/{walletId}/pin-changes: post: description: This API will send a USSD push to the customers registered phone asking them to enter ID and old pin and new pin. POST can be empty. Can be used by TPP. summary: initiatePinChange operationId: walletsPinChangesByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: type: string responses: 203: description: OK headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' /wallets/{walletId}/consent-removals: post: description: This API will send a USSD push to the customers registered phone asking them if they want to remove all consent from third parties to access their wallet. Can be used by TPP. summary: initiateConsentRemoval operationId: walletsConsentRemovalsByWalletIdPost tags: - Wallet x-swagger-router-controller: Wallet deprecated: false produces: - application/json parameters: - name: walletId in: path required: true type: string description: "" - name: body in: body required: false description: "" schema: type: string responses: 203: description: OK headers: [] 500: description: Internal Server error schema: $ref: '#/definitions/ExceptionData' /isup: get: description: "" summary: getResult operationId: isupGet tags: - Default x-swagger-router-controller: Default deprecated: false produces: - text/plain parameters: [] responses: 200: description: default response schema: type: string headers: [] parameters: x-nb-subscription-id: in: header name: x-nb-subscription-id type: string required: true description: subscription record id x-fapi-interaction-id-Param: in: header name: x-fapi-interaction-id type: string required: false description: An RFC4122 UID used as a correlation id. Authorization-Param: in: header name: Authorization type: string required: true description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750 x-ibm-client-id: in: header name: x-ibm-client-id type: string required: true description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750 x-ibm-client-secret: in: header name: x-ibm-client-secret type: string required: true description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750 definitions: CallbackResponse: type: object properties: CallbackId: type: string description: The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback. ExceptionData: title: ExceptionData type: object properties: code: type: string severity: $ref: '#/definitions/Severity' type: $ref: '#/definitions/Type' description: type: string QrCodeInfo: title: QrCodeInfo description: Data representing a decoded QrCode type: object properties: Amount: description: Total amount to be paid or null if no amount is embedded type: number format: double UnitType: description: ISO_4217 currency code of the amount or some other unit type type: string Description: description: Description type: string MerchantIdentifier: description: Some identifier for the merchant or null type: string MerchantName: description: Name of the merchant or null type: string TransactionReference: description: Some unique reference for the code if there is one or else null type: string qrCodeType: type: string Avp: title: Avp description: A generic attribute/value pair used on various models for storing generic weakly typed supplementary data type: object properties: Att: description: Attribute name type: string Val: description: Attribute value type: string Wallet: title: Wallet description: Representation of a Wallet type: object properties: CallbackId: description: The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback. type: string WalletId: description: Unique unnatural key for the Wallet which will never ever change Wallets can also have zero or more mappings (alias) that can also uniquely identity each wallet type: string ParentWalletId: description: Wallet id of the parent (enabling hierarchies) type: string WalletType: description: The type of wallet - the type dictates various business rules and the underlying store of value type: string CurrentBalance: description: The total balance in the wallet. All may not be available for use (due to reservations) type: number format: double AvailableBalance: description: Current balance less any reservations or minimum balance requirements type: number format: double UnitType: description: UnitType of the store of value of the wallet. Could be a currency code or some arbitrary unit type like minutes type: string UserId: description: Associated user who owns the wallet (optional if its an impersonal wallet) type: string OrganisationId: description: Associated organisation who owns the wallet (optional) type: string Status: $ref: '#/definitions/WalletStatus' Created: description: Date/Time of when the wallet was created (ISO 8601) type: string format: date-time SupplementaryData: description: General weakly typed data about the wallet type: array items: $ref: '#/definitions/Avp' WalletStatus: title: WalletStatus description: Holds the status of a Wallet. Likely to expand over time as new statuses are added type: object properties: Locked: description: The wallet is locked and cannot accept any reservations, debits nor credits type: boolean ReservationResponse: title: ReservationResponse description: Result for a reservation on a wallet type: object properties: ReservationId: description: A reference for the reservation type: string CreateReservationRequest: title: CreateReservationRequest description: A reservation against a wallet. Reservations prevent any access to the locked funds and result in a difference between the current and available balance type: object properties: SessionId: description: An identifier passed by the calling system to tie together one or more reservations to a long running transaction type: string Amount: description: The amount of the reservation in the currency/units of the associated walletId type: number format: double Expires: description: Date/Time of when the reservation will be automatically released (ISO 8601) type: string format: date-time Description: description: A free text field storing the description of the reservation for customers to understand what the reservation is for type: string ExternalUniqueId: description: An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids type: string Reservation: title: Reservation description: A reservation against a wallet. Reservations prevent any access to the locked funds and result in a difference between the current and available balance type: object properties: SessionId: description: An identifier passed by the calling system to tie together one or more reservations to a long running transaction type: string Amount: description: The amount of the reservation in the currency/units of the associated walletId type: number format: double Expires: description: Date/Time of when the reservation will be automatically released (ISO 8601) type: string format: date-time Description: description: A free text field storing the description of the reservation for customers to understand what the reservation is for type: string ExternalUniqueId: description: An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids type: string ReservationId: description: Unique system generated identifier for the reservation. This is an unnatural key. type: string WalletId: description: The walletId that this reservation is against type: string Created: description: Date/Time of when the reservation was created (ISO 8601) type: string format: date-time WalletMapping: title: WalletMapping description: Holds a mapping between external identifiers and a wallet. Effectively an alias to a wallet. type: object properties: ExternalId: description: Some external identifier. E.g. a persons phone number, QRCode etc. Combination of externalId and externalIdType must be unique across all wallets type: string ExternalIdType: $ref: '#/definitions/ExternalIdType' Priority: description: The priority of this mapping for cases where a mapping could map to many wallets. Higher value indicates higher priority. Highest priority is considered to be the main or master wallet type: integer format: int32 Peer2PeerResponse: title: Peer2PeerResponse description: Result for a transfer from one wallet to another type: object properties: CallbackId: description: The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback. type: string DebitTransactionId: description: The transaction id for the debit leg of the transaction type: string CreditTransactionId: description: The transaction id for the credit leg of the transaction type: string Peer2PeerRequest: title: Peer2PeerRequest description: Data for requesting a peer-to-peer transfer from one wallet to another type: object properties: CallbackUrl: description: A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time. type: string ToWallet: $ref: '#/definitions/WalletIdentifier' Amount: description: The amount in the unit type of the from and to wallet type: number format: double Description: description: Description to appear on the transaction history type: string ExternalUniqueId: description: An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids type: string Channel: description: Channel originating the transaction (actual codes TBD) type: string Location: description: Location of the transaction (actual codes TBD) type: string SupplementaryData: description: Other generic data relating to the transaction which is weakly typed type: array items: $ref: '#/definitions/Avp' WalletIdentifier: title: WalletIdentifier description: Uniquely identifies a Wallet. Either the WalletId or WalletMapping should be populated. If a WalletId as well as WalletMapping is populated then an exception will be thrown. This helps prevent misunderstandings if the Mapping & Id contradict each other type: object properties: WalletId: description: WalletId to uniquely identify the wallet type: string WalletMapping: $ref: '#/definitions/WalletMapping' AtmOutResponse: title: AtmOutResponse description: Data representing an ATM withdrawal response type: object properties: CallbackId: description: The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback. type: string AtmOtp: description: The OTP to be used at an ATM to do the withdrawal type: string AtmOutRequest: title: AtmOutRequest description: Data representing an ATM withdrawal request type: object properties: CallbackUrl: description: A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time. type: string ExternalUniqueId: description: Unique external identifier for the withdrawal to prevent duplicate requests being processed type: string EftOutResponse: title: EftOutResponse description: Data representing a response to a request to EFT money out of a wallet and into a bank account type: object properties: CallbackId: description: The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback. type: string TransactionId: description: The transaction id for the transaction type: string EftOutRequest: title: EftOutRequest description: Data representing a request to EFT money out of a wallet and into a bank account type: object properties: CallbackUrl: description: A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time. type: string AccountNumber: description: Destination account number type: string BranchCode: description: Destination branch code type: string Bank: description: Destination bank name type: string RecipientReference: description: The description that the recipient will see on their statement type: string OwnReference: description: The description that the recipient will see on their statement type: string ExternalUniqueId: description: An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids type: string amount: type: number format: double QrCodePaymentResponse: title: QrCodePaymentResponse description: Data representing a response to a request to pay a QRCode type: object properties: TransactionId: description: The transaction id for the transaction type: string QrCodePaymentRequest: title: QrCodePaymentRequest description: Data representing a request to pay money to a QRCode from a wallet type: object properties: QrCode: description: The string of the decoded QRCode type: string ExternalUniqueId: description: An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids type: string amount: type: number format: double PurchaseVasResponse: title: PurchaseVasResponse description: Result data after requesting the purchase of a value added service type: object properties: CallbackId: description: The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback. type: string Amount: description: The amount charged against the wallet for the purchase type: number format: double VoucherId: description: The VAS voucher Id/PIN if applicable type: string TransactionId: description: The transaction id for the transaction type: string PurchaseVasRequest: title: PurchaseVasRequest description: Data for requesting the purchase of a value added service type: object properties: CallbackUrl: description: A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time. type: string Amount: description: The amount for purchases such as airtime which have a non-fixed amount type: number format: double Msisdn: description: The phone number in format 27XXXXXXXXX to provision the VAS against or SMS appropriate voucher codes to. Note that this does not decide what wallet is charged - the charged wallet id is specified as a path parameter on the request URL type: string ProductId: description: The VAS product to purchase. Product Id's and prices are updated and available out of band type: string ExternalUniqueId: description: An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids type: string ImpersonalResponse: title: ImpersonalResponse description: Result for an impersonal account transfer type: object properties: CallbackId: description: The ID (GUID) that will be in the callback POST data when the callback happens. Will be null if the response is synchronous and is not via callback. type: string DebitTransactionId: description: The transaction id for the debit leg of the transaction type: string CreditTransactionId: description: The transaction id for the credit leg of the transaction type: string ImpersonalRequest: title: ImpersonalRequest description: Data for requesting transfer from/to an impersonal account type: object properties: CallbackUrl: description: A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of bacnd authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time. type: string ImpersonalAccountName: description: The special name for the impersonal account type: string Amount: description: The amount in the unit type of the from and to wallet type: number format: double Description: description: Description to appear on the transaction history type: string ExternalUniqueId: description: An external unique Id to identity this transaction and prevent unintended replays. System will reject duplicate ids type: string Channel: description: Channel originating the transaction (actual codes TBD) type: string Location: description: Location of the transaction (actual codes TBD) type: string SupplementaryData: description: Other generic data relating to the transaction which is weakly typed type: array items: $ref: '#/definitions/Avp' CreateWalletRequest: title: CreateWalletRequest description: Data for the creation of a new Wallet type: object properties: CallbackUrl: description: A URL that will be POSTed to with the response if the caller cannot wait for a synchronous response due to the transaction potentially taking a few minutes due to out of band authorisation. If provided, an immediate response will come back with a callbackId and the actual callback eith that callbackId will come later via the POST to the callbackUrl. If null or empty then response will be synchronous even if it takes a long time. type: string ExternalUniqueId: description: An external unique Id to identity this transaction and prevent/unintended replays. System will reject duplicate ids type: string FirstName: description: FirstName. Combination of firstname and lastname must be less than 40 characters type: string LastName: description: LastName. Combination of firstname and lastname must be less than 40 characters type: string IdentityNumber: description: Identity Number. 13 digits type: string Msisdn: description: Msisdn. In format 27xxxxxxxxx or 0xxxxxxxxx type: string IncomeSourceType: description: Income Source Type (see /configuration/income-types) type: string IndustryType: description: Industry Types (see /configuration/industry-types) type: string OccupationType: description: Occupation Types (see /configuration/occupation-types) type: string CustomerApproveRequest: type: object CustomerApproveResponse: type: object properties: CallbackId: type: string Status: type: string CreateHeavyTokenResp: type: object properties: access_token: type: string refresh_token: type: string scope: type: string token_type: type: string expires_in: type: string ExternalIdType: title: ExternalIdType description: Holds the allowed types of externalIdType example: IdentityNumber type: string enum: - IdentityNumber - Msisdn - OrganisationId - CisReference - UserId CatalogueQueryResponse: type: object properties: Category: $ref: '#/definitions/Category' ChildCategories: $ref: '#/definitions/ChildCategories' ChildCategories: type: array items: $ref: '#/definitions/Category' Category: type: object properties: CategoryID: type: string Code: type: string Name: type: string WebIcon: type: string IOSIcon: type: string AndroidIcon: type: string Description: type: string ProductCount: type: integer format: int32 Type: type: string Products: type: array items: $ref: '#/definitions/ProductData' ProductData: type: object properties: ProductID: type: string Name: type: string Code: type: string Price: type: string AverageSpend: type: string Vendor: type: string WebIcon: type: string AndroidIcon: type: string AdditionalContent: type: string Status: type: string BillingType: type: string Description: type: string PublishedDate: type: string MinAmount: type: string MaxAmount: type: string IncomeTypesResponse: type: array items: $ref: '#/definitions/ReferenceData' IndustryTypesResponse: type: array items: $ref: '#/definitions/ReferenceData' OccupationTypesResponse: type: array items: $ref: '#/definitions/ReferenceData' ReferenceData: type: object properties: Code: type: string Description: type: string ParentIDCode: type: string Severity: title: Severity example: CRITICAL type: string enum: - CRITICAL - HIGH - MEDIUM - INFO - LOW Type: title: Type example: BUSINESS type: string enum: - BUSINESS - SYSTEM tags: - name: Wallet description: "" x-ibm-configuration: enforced: true testable: true phase: realized securityDefinitions: TPPOAuth2Security: type: oauth2 description: TPP client credential authorisation flow with the ASPSP flow: application scopes: tpp_client_credential: TPP Client Credential Scope tokenUrl: https://api.nedbank.co.za/apimarket/sandbox/nboauth/oauth20/token x-tokenIntrospect: url: https://api-market.nedsecure.nednet.co.za/mga/sps/oauth/oauth20/introspect PSUOAuth2Security: type: oauth2 description: OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU flow: accessCode scopes: wallet: "" openid: cc309236 authorizationUrl: https://api.nedbank.co.za/apimarket/sandbox/oauth/oauth20/authorize tokenUrl: https://api.nedbank.co.za/apimarket/sandbox/nboauth/oauth20/token x-tokenIntrospect: url: https://api-market.nedsecure.nednet.co.za/mga/sps/oauth/oauth20/introspect X-IBM-Client-Secret: type: apiKey description: "" in: header name: X-IBM-Client-Secret X-IBM-Client-Id: type: apiKey description: "" in: header name: X-IBM-Client-Id security: - X-IBM-Client-Secret: [] X-IBM-Client-Id: [] TPPOAuth2Security: - tpp_client_credential x-ibm-endpoints: - endpointUrl: https://api.nedbank.co.za/apimarket/sandbox type: - production ...