swagger: '2.0' info: description: |- To facilitate the capability for consumers to make a payment or refund to service providers. version: v1.0 title: Payments V1 contact: name: MADAPI Development Team url: 'https://developers.mtn.com/contact' email: developer-support@mtn.com schemes: - https host: api.mtn.com basePath: /v1 consumes: - application/json produces: - application/json securityDefinitions: OAuth2: type: oauth2 flow: application tokenUrl: 'https://api.mtn.com/v1/oauth/access_token' security: - OAuth2: [] tags: - name: Retrieve Payment Status - name: Submit Payment or Refund Request paths: /payments: post: tags: - Submit Payment or Refund Request summary: Provides the ability for a consumer to make a payment or refund to service providers. description: Provides the ability for a consumer to make a payment or refund to service providers. operationId: createPayment parameters: - name: paymentRequest in: body description: Payment that is created. required: true schema: $ref: '#/definitions/PaymentRequest' - name: X-Authorization in: header description: Encrypted ECW credentials required: false type: string responses: '200': description: Success schema: $ref: '#/definitions/PaymentResponse' headers: transactionId: type: string description: Payment TransactionId as generated by MADAPI x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc '201': description: Successful payment generated. schema: $ref: '#/definitions/PaymentResponse' headers: Location: type: string description: Location header will include the link to the newly created payment. '204': description: Success schema: $ref: '#/definitions/PaymentResponse' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Customer not found schema: $ref: '#/definitions/Error' '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' '/payments/{correlatorId}/transactionStatus': get: tags: - Retrieve Payment Status summary: Provides the status of a Payment Transaction to service providers. description: Provides the status of a Payment Transaction to service providers. operationId: getPaymentTransactionStatus parameters: - name: correlatorId in: path description: Unique identifier in the client for the payment in case it is needed to correlate, could also be a reference id generated when making the request type: string x-example: c5f80cb8-dc8b-11ea-87d0-0242ac130003 required: true - name: transactionId in: header description: Client generated Id to include for tracing requests. type: string x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc - name: X-Authorization in: header description: Encrypted ECW credentials required: false type: string - name: amount type: number in: query - name: targetSystem type: string in: query description: target system expected to fulful the service enum: [EWP, ECW, CELD] - name: paymentType type: string in: query description: Type of the transaction enum: [Airtime] - name: customerId type: string in: query description: This is the payer mobile number ie. MSISDN. Could be ID:122330399/MSISDN - name: description in: query type: string description: can be a payer note, a merchant identifier ie. merchantId etc. responses: '200': description: Success schema: $ref: '#/definitions/PaymentTransactionStatusResponse' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Customer not found schema: $ref: '#/definitions/Error' '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /payments/{id}/history: get: tags: - Payment History summary: Get a list of payments made on a reference or by a customer id description: Get a list of payments made on a reference or by a customer id operationId: getPaymentHistory parameters: - name: id in: path description: Unique identifier in the client for the payment in case it is needed to correlate. type: string x-example: c5f80cb8-dc8b-11ea-87d0-0242ac130003 required: true - name: X-Authorization in: header type: string description: An authorization claim to be passed by the caller - name: transactionId in: header description: Client generated Id to include for tracing requests. type: string x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc - name: targetSystem type: string in: query description: target system expected to fulful the service enum: [CPG, EWP] - name: segment in: query type: string description: Segment of the customer. For example, subscriber,agent, merchant, admin depending on the type of customer whome the operation is being performed against. enum: [subscriber,agent, merchant, admin] - name: idType type: string in: query required: false description: Type of the customerId in the path. enum: [MSISDN, USER] - name: pageSize in: query description: "Maximum number of items to get from the backend system" type: number x-example: "10" - name: pageNumber in: query description: "Current page or offset number" type: number x-example: "0" - name: status in: query description: "Status of the transactions" type: string x-example: "SUCCESSFUL" - name: requestType in: query type: string description: "type of request" enum: ["MOMO"] - name: nodeId type: string in: query description: Node making the request x-example: Comviva - name: startTime type: string in: query description: Start time of the transaction.If blank, then transaction received date will be set as start time x-example: 20210622131709 - name: startDate type: string in: query description: Start date of the history range x-example: 20210622131709 - name: endDate type: string in: query description: End date of the history range x-example: 20220629120000 - name: queryType type: string in: query description: Type of request x-example: Y - name: registrationChannel type: string in: query description: Channel making the request x-example: SMS - name: traceId type: string in: query description: Unique identifier from the caller x-example: 156135egfSfgfgadg09676 responses: '200': description: Success schema: $ref: '#/definitions/PaymentHistoryResponse' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Customer not found schema: $ref: '#/definitions/Error' '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /payments/payment-link: post: tags: - Generate a payment link for account payment summary: Provides the ability for a consumer to generate a payment link for account payment description: Provides the ability for a consumer to get the payment link for the requesting MSISDN so as to enable the customer to make payment to the service providers. operationId: generatePaymentLink parameters: - name: orderRequest in: body description: Order details for the payment link that is to be created. required: true schema: $ref: '#/definitions/OrderRequest' - name: transactionId in: header description: Client generated Id to include for tracing requests. type: string x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc required: false responses: '200': description: Success schema: $ref: '#/definitions/OrderResponse' '201': description: Success schema: $ref: '#/definitions/OrderResponse' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Customer not found schema: $ref: '#/definitions/Error' '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /payments/payment-agreement/eligibility: get: tags: - Generate a payment agreement summary: Provides the ability for a consumer to check the eligibility status for payment agreement description: Provides the ability for a consumer to check the eligibility status for payment agreement so as to enable the customer to make payment to the service providers. operationId: getPaymentAgreementEligibility parameters: - name: billingAccountNumber in: query type: string description: Singleview billing account number. required: true - name: transactionId in: header description: Client generated Id to include for tracing requests. type: string x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc required: false responses: '201': description: Success schema: $ref: '#/definitions/promiseToPayEligibilityResponse' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Customer not found schema: $ref: '#/definitions/Error' '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /payments/payment-agreement: post: tags: - Generate a payment agreement summary: Provides the ability for a consumer to generate a payment agreement (Promise to Pay) description: Provides the ability for a consumer to generate a payment agreement (Promise to Pay) so as to enable the customer to make payment to the service providers. operationId: generatePaymentAgreement parameters: - name: promiseToPayRequest in: body description: Agreement details for the payment promise that is to be created. required: true schema: $ref: '#/definitions/promiseToPayRequest' - name: transactionId in: header description: Client generated Id to include for tracing requests. type: string x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc required: false responses: '201': description: Success schema: $ref: '#/definitions/promiseToPayResponse' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Customer not found schema: $ref: '#/definitions/Error' '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /reverse-payment/history: get: tags: - Reverse Payment summary: Provides the history or list of revese transactions to third party. description: Provides the status of a Payment Transaction to service providers. operationId: getReverseTransactionHistory parameters: - name: "customerId" in: header description: 'Unique identifier of the customer. It should be financial resource identification in case of target system is ECW' type: string x-example: 'FRI:266456789/MSISDN' required: true - name: "correlatorId" in: header description: 'Unique identifier in the client for the payment in case it is needed to correlate.' type: string x-example: 'c5f80cb8-dc8b-11ea-87d0-0242ac130003' required: false - name: "transactionId" in: header description: 'Client generated Id to include for tracing requests.' type: string x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc' - name: "transactionstatus" in: header description: 'This is the provider that is expected to fulfill the query transaction service' type: string required: false - name: transactiontype in: query description: 'transactiontype' type: string required: true - name: amount in: query description: 'amount of the transaction' required: false type: number format: float - name: X-Authorization in: header description: 'Encrypted ECW credentials' required: false type: string - name: nodeId in: query description: Third parties unique identifier. Can also be called channelId. type: string required: false - name: startDate in: query description: >- Retrieve transaction history created from this start date. type: string required: false - name: endDate in: query description: >- Retrieve transaction history created until this stop date. type: string required: false - name: otherFri in: query description: >- The FRI of the other party in transaction, could be from or to depending on direction. Validated with IsFRI. type: string required: false - name: posMsisdn in: query description: >- Retrieve transaction history performed be the specified point of sale MSISDN. type: string required: false - name: quoteId in: query description: >- List all information based on quoteId then quoteId used. type: string required: false - name: limit in: query description: The maximum number of items to return in the response. Default value 50. type: integer default: 1 - name: pageNo in: query description: >- indexoffset the list of results returned by an API. Optional, If its not specified we should return all the values. type: integer default: All result required: false responses: '200': description: 'Success' schema: $ref: "#/definitions/ReverseTransactionHistory" '400': description: "Bad Request" schema: $ref: "#/definitions/Error" '401': description: "Unauthorized" schema: $ref: "#/definitions/Error" '403': description: "Forbidden" schema: $ref: "#/definitions/Error" '404': description: "Customer not found" schema: $ref: "#/definitions/Error" examples: The services object/envelope will be null: > { "services": null } '405': description: "Method Not allowed" schema: $ref: "#/definitions/Error" '500': description: "Internal Server Error" schema: $ref: "#/definitions/Error" '/payments/fee': post: tags: - p2p transfer fee check description: "Provides the ability for a consumer to check a payment transfer fee charged by service providers." summary: check transfer fee/charges beforhand operationId: inbound consumes: - application/json produces: - application/json parameters: - name: body in: body required: true description: request body schema: $ref: '#/definitions/FeecheckRequest' responses: 200: description: "Success" schema: $ref: "#/definitions/InboundResponse" 400: description: "Bad Request" schema: $ref: "#/definitions/BadFeeRequest" 500: description: "Internal Server Error" schema: $ref: "#/definitions/FeeRequestNotFound" definitions: PaymentRequest: description: Payment Request details. type: object properties: correlatorId: type: string description: Unique identifier in the client for the payment in case it is needed to correlate, a trace id associated with the caller example: c5f80cb8-dc8b-11ea-87d0-0242ac130003 paymentDate: type: string format: date-time description: Date when the payment was performed. example: '2020-08-12T11:04:53.668Z' name: type: string description: Screen name of the payment. example: Manual Boost for RWC callingSystem: $ref: '#/definitions/CallingSystemEnum' transactionType: $ref: '#/definitions/TransactionTypeEnum' targetSystem: $ref: '#/definitions/TargetSystemEnum' callbackURL: type: string description: The callback URL. example: 'https://myCallBack/url' quoteId: type: string description: The ID of the quote used, a terminal id associated with the caller. example: '9223372036854775807' channel: type: string description: The channel used to perform the payment operation or just the channel itself with just its name. example: AYO description: type: string description: Text describing the contents of the payment. example: Manual Boost for RW authorizationCode: type: string description: Authorization code retrieved from an external payment gateway that could be used for conciliation. example: feeBearer: type: string description: Who bears a charge for a particular transaction , whether a Payer or Payee enum: - Payer - Payee amount: $ref: '#/definitions/MoneyType' taxAmount: $ref: '#/definitions/MoneyType' totalAmount: $ref: '#/definitions/MoneyType' payer: $ref: '#/definitions/Payer' payee: type: array items: $ref: '#/definitions/Payee' paymentMethod: $ref: '#/definitions/PaymentMethod' status: type: string description: Status of the payment method. example: Pending statusDate: type: string format: date-time description: Time the status of the payment method changed. example: '2020-08-12T11:04:53.668Z' additionalInformation: type: array items: $ref: '#/definitions/AdditionalInformation' segment: type: string description: Segment of the customer. Forexample, subscriber,agent, merchant, admin depending on the type of customer whome the operation is being performed against. enum: [subscriber,agent, merchant, admin] required: - totalAmount - paymentMethod - correlatorId - transactionType - countryCode - callbackURL OrderRequest: description: Order Request details. allOf: - required: - channel - quoteId - description - authenticationType - deliveryMethod - payer - totalAmount - itemDetails type: object properties: channel: type: "string" description: "Source system (Channel) identifier" example: 'Facebook' quoteId: type: string description: The ID of the quote used. example: '9223372036854775807' description: type: string description: Text describing the contents of the payment. example: Manual Boost for RW authenticationType : type : string description : This field will have the authentication type that the channel prefers to have for making a payment. Pass it as "Query Payment" incase if you don't need any back update notification about payment. Possible values are [Query Payment, Inline Auth, Notification] example: 'Query Payment' callbackUrl: type : string description : This field will have the call back URL to notify the payment status to the channels. This field should only be passed if authenticationType is Notification. The source channel initiating the order should give the notifyURL redirectUrl: type: string description: This field will be the self service channel web page URL where the user is supposed to be once the payment is done on payportal deliveryMethod : type : string description : Method through which link need to be shared. In case of "SMS" URL is sent via SMS. In case of "Paylink" URL will be sent part of response. Possible values are [SMS, Payweb, Email, Paylink] example : 'Paylink' payer: $ref: '#/definitions/Payer' paymentmethods: type: array items: type: string enum: - Card Payment - MoMo - Airtime - Loyalty - Bank EFT - Add to Bill totalAmount: $ref: '#/definitions/MoneyType' itemDetails : type : array description : '' items : type : object allOf: - required: - itemName - itemDescription - itemValue - currency - quantity properties: itemName : type : string description : Name of the item placed by the customer. Possible values are [ITEM_PURCHASE, ACCOUNT_PAYMENT] example: 'ACCOUNT_PAYMENT' itemDescription : type : string description : Description of the item placed by the customer itemValue : type : string description : This field will have the amount of the item example: 200 currency : type : string description : This field will have the uom for the itemValue example: ZAR quantity : type : integer description : This field will have number of items placed by the customer example: '1' AdditionalInformation: description: Additional information related to the item details. type: array items: properties: name: type: string description: Name of additional information item. example: 'BundleName' description: type: string description: Description of additional information item. example: 'Voice_1111' required: - name - description OrderResponse: type: object properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '0000' statusMessage: type: string description: Message of the transaction. Either Success or Failure. transactionId: type: string description: Unique identifier for every request to the backend. Mapped from input request. example: 5345345 sequenceNo: type: string description: A unique id for tracing all requests example: 12345 data: $ref: '#/definitions/DataOrder' _links: $ref: '#/definitions/OrderResponse__Links' OrderResponse__Links: type: object properties: self: $ref: '#/definitions/OrderResponse__Links_Self' OrderResponse__Links_Self: type: object properties: href: type: string example: 'https://host:port/payments/payment-link/' description: Hyperlink to access the payment link generation endpoint. DataOrder: type: object properties: providerTransactionId: type: string example: FT172145YB21 description: 'ID of the payment, generated by back-end system. This can be blank if the payment has previously been pre-approved.' orderRedirectUrl: type: string description: This will have the encrypted url that will be route to pay portal on click. MoneyType: description: Representation of monetary value. type: object properties: amount: format: decimal type: number description: Amount of money example: 50 units: type: string description: Currency example: XOF required: - amount - units MoneyCurrencyType: description: Representation of monetary value. properties: amount: format: decimal type: number description: 'Amount of money' example: '50.00' currency: type: string description: 'Currency' example: 'XOF' required: - amount - currency Payer: description: The individual that performs the payment. type: object properties: payerIdType: type: string description: Identifier Type of the Payer. example: MSISDN payerId: type: string description: The Payer identifier, can be a sending fri, an msisdn etc. example: '233364654737' payerNote: type: string description: A descriptive note for sender transaction history,ex. a sender note example: Manual Boost for RWC payerName: type: string description: Name of the payer payerEmail: type: string description: An optional email address of the payer or customer payerRef: type: string description: A reference to the payer example: "233364654737" payerSurname: type: string description: Surname of the payer example: "Orimoloye" includePayerCharges: type: boolean description: A boolean value to add payment charges example: false required: - payerId Payee: description: 'A payment can be made in the context of an order, a recharge, for ongoing bills, for administrative fee (e.g. re-sending a paper copy of a bill), damaged device penalty, and more.' type: object properties: amount: $ref: '#/definitions/MoneyType' taxAmount: $ref: '#/definitions/MoneyType' totalAmount: $ref: '#/definitions/MoneyType' payeeIdType: type: string description: Identifier Type of the Payee. example: USER payeeId: type: string description: The Payee identifier, ie. can be a receivingfri or a merchant Id etc. example: AYO.DEPOSIT payeeNote: type: string description: A descriptive note for receiver transaction history, ie. a receiver message example: Manual Boost for RWC payeeName: type: string description: Name of the payee required: - totalAmount - payerIdType - payerId AdditionalInformation: description: Additional information relating to the payment transaction. type: object properties: name: type: string description: Name of additional information item. example: BundleName description: type: string description: Description of additional information item. example: Voice_1111 required: - name - description MetaData: description: An array of additional information related to the payment type: array items: $ref: '#/definitions/AdditionalInformation' PaymentMethod: description: Reference or value of the method used to process the payment. type: object properties: name: type: string description: Friendly name assigned to the payment method. example: Manual Boost for RWC description: type: string description: Description of the associated payment method. example: Manual Boost for RWC validFrom: type: string format: date-time description: Period the payment method is valid. example: '2021-07-21T17:32:28Z' validTo: type: string format: date-time description: Period the payment method is valid. example: '2021-07-21T17:32:28Z' type: $ref: '#/definitions/PaymentMethodTypeEnum' details: $ref: '#/definitions/PaymentMethodTypeDetails' required: - type PaymentMethodTypeEnum: type: string title: PaymentMethodTypeEnum enum: - BankCard - TokenizedCard - BankAccountDebit - BankAccountTransfer - Account - LoyaltyAccount - Bucket - Voucher - DigitalWallet - Airtime - Mobile Money - Invoice x-enum-elements: - name: BankCard description: Use a Bank Card to pay. - name: TokenizedCard description: Use a Tokenized Card to pay. - name: BankAccountDebit description: Use a Bank Account Debit to pay. - name: BankAccountTransfer description: Use a Bank Account Transfer to pay. - name: Account description: Use a Telco Account to pay. - name: LoyaltyAccount description: Use a Loyalty Account to pay. - name: Bucket description: Use a Bucket to pay. Especially used in the Pre-Paid environment. - name: Voucher description: Use a Vouher to pay. - name: DigitalWallet description: Use a Digital Wallet to pay. - name: Invoice description: Create an invoice or pay to an already scheduled invoice TransactionTypeEnum: type: string title: TransactionTypeEnum description: The transaction type that is associated with the payment transaction. enum: - Payment - Debit - Transfer - Refund default: Payment example: Debit CallingSystemEnum: type: string title: CallingSystemEnum description: The name of the calling system. enum: - ECW - AYO - POS - IVR TargetSystemEnum: type: string title: TargetSystemEnum description: The name of the target system. enum: - ECW - AYO - EWP - OCC - CPG - CELD LoyaltyBalances: type: object description: Contains all the loyalty balances associated with a customer. properties: generatedAmount: $ref: '#/definitions/MoneyType' consumedAmount: $ref: '#/definitions/MoneyType' newBalance: $ref: '#/definitions/MoneyType' PaymentMethodTypeDetails: description: Definition of the payment method. Its content depends on the type field. type: object properties: bankCard: $ref: '#/definitions/BankCard' tokenizedCard: $ref: '#/definitions/TokenizedCard' bankAccountDebit: $ref: '#/definitions/BankAccountDebit' bankAccountTransfer: $ref: '#/definitions/BankAccountTransfer' account: $ref: '#/definitions/Account' loyaltyAccount: $ref: '#/definitions/LoyaltyAccount' bucket: $ref: '#/definitions/Bucket' voucher: $ref: '#/definitions/Voucher' digitalWallet: $ref: '#/definitions/DigitalWallet' invoice: $ref: '#/definitions/InvoiceMethod' InvoiceMethod: description: Detailed information for an invoice type: object properties: id: type: string description: This is the Id of the invoice example: 86rer4478878t991 type: type: string description: Type of the invoice being paid for example: trigger frequency: type: string description: This is the frequency of a reccuring transaction enum: - 'on_call' - 'once' - 'hourly' - 'daily' - 'weekly' - 'every_[1-366]d' startDate: type: string description: This is the start date of a reccuring transaction example: '2021-03-20' endDate: type: string description: This is the end date of a reccuring transaction example: '2021-09-20' retryOnFail: type: boolean description: A boolean to showing if the transaction should be retried on fail or not. example: true deactivateOnFail: type: string description: A boolean to showing if the transaction should be deactivated on fail or not. example: true callbackUrl: type: string description: The url to be invoked for callbacks example: 'https://merchant-application-url/webhook-endpoint' retryRun: type: string description: This is the retry run example: 1-5 retryFrequency: type: string description: The retry frequencies enum: - 'once' - 'hourly' - 'daily' BankCard: description: Detailed information for a bank card. type: object properties: brand: type: string description: 'Card brand. e.g. Visa, MasterCard, AmericanExpress.' example: Visa type: type: string description: 'Type of card. e.g. Credit, Debit.' example: Credit cardNumber: type: string description: Credit card number. example: xxxx xxxx xxx xxx expirationDate: type: string format: date-time description: Expiration date of the card. example: '2021-07-21T17:32:28Z' cvv: type: string description: 'Security Code of the card. e.g. CCV, CCV2.' example: '123' lastFourDigits: type: string description: Last four digits of the credit card. example: '1234' nameOnCard: type: string description: Name on the card. example: Bruce Wayne bank: type: string description: Bank that issued the card. example: Bank of Gotham pin: type: string description: Customer pin created when tokenizing the card example: '123' TokenizedCard: description: Detailed information for a stored tokenized card. type: object properties: brand: type: string description: Card brand. Might be used for display purposes. type: type: string description: Card type. Might be used for display purposes. lastFourDigits: type: string description: Last four digits of the credit card or a token authentication PIN. Might be used for display purposes. tokenType: type: string description: Token type. e.g emv. token: type: string description: The token itself ie. a token id associated with a the payment card. issuer: type: string description: Whoever issued the token. BankAccountDebit: description: Detailed information for a bank account debit. type: object properties: accountNumber: type: string description: Bank Account Number (this could refer to the IBAN or SWIFT number). accountNumberType: type: string description: 'Type of account number. e.g. IBAN, SWIFT.' BIC: type: string description: Business Identifier Code/Swift code of the financial institution where the account is located. owner: type: string description: Owner of the bank account. bank: type: string description: Display nam of the bank. BankAccountTransfer: description: Detailed information for a bank account transfer. type: object properties: accountNumber: type: string description: Bank Account Number (this could refer to the IBAN or SWIFT number). accountNumberType: type: string description: 'Type of account number. e.g. IBAN, SWIFT.' BIC: type: string description: Business Identifier Code/Swift code of the financial institution where the account is located. owner: type: string description: Owner of the bank account. bank: type: string description: Display nam of the bank. Account: description: Detailed information for a Telco Account. type: object properties: id: type: string description: Unique identifier of the account. name: type: string description: Entity name. description: type: string description: Description of the associated account. LoyaltyAccount: description: Detailed information for a loyalty system that could be used to perform the payment.. type: object properties: id: type: string description: Unique identifier of the loyalty account. name: type: string description: Entity name. description: type: string description: Description of the associated loyalty account. Bucket: description: 'Detailed information for a bucket that could be used to perform the payment, especially in the pre-paid environment.' type: object properties: id: type: string description: Unique identifier of the bucket. name: type: string description: Entity name. description: type: string description: Description of the associated bucket. Voucher: description: Detailed information for a voucher. type: object properties: code: type: string description: Code that identifies the voucher. description: type: string description: 'Description of the voucher. i,e, Get one and receive one free.' value: type: string description: Discount that the voucher applies when its a discount voucher. expirationDate: type: string format: date-time description: The vouchers expiration date. campaign: type: string description: Campaign this voucher belongs to. DigitalWallet: description: Detailed information for a Digital Wallet. type: object properties: service: type: string description: 'Organization, platform or currency backing the wallet. e.g. MoMo, PayPal, Yandex, BitCoin. Can also be an extension of a service being paid for' example: MoMo walletId: type: string description: Account identifier in that service. example: '233364654737' walletUri: type: string description: URI pointing at the digital wallet. example: 'https://paypal.me/johndoe' PaymentResponse: type: object properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '0000' providerTransactionId: type: string example: FT172145YB21 description: 'ID of the payment, generated by back-end system. This can be blank if the payment has previously been pre-approved.' statusMessage: type: string description: 'A description of the transaction status.' supportMessage: type: string description: 'A description used for error handling' sequenceNo: type: string description: 'A unique id for tracing all requests' example: 1234 fulfillmentStatus: type: string description: 'A description of the transaction fulfillment status.' enum: - 'Succesful' - 'Failed' - 'Null' data: $ref: '#/definitions/Data' _links: $ref: '#/definitions/PaymentResponse__Links' PaymentResponse__Links_Self: type: object properties: href: type: string example: 'https://host:port/payments/v1/12345' description: Hyperlink to access the financial payment. PaymentResponse__Links: type: object properties: self: $ref: '#/definitions/PaymentResponse__Links_Self' description: Relevant links to the financial payment. Data: type: object properties: approvalId: type: string description: Unique identifier in the client for the payment in case it is needed to correlate. Generated by back-end system. This can be blank if the payment has previously been pre-approved. transactionFee: $ref: '#/definitions/MoneyType' discount: $ref: '#/definitions/MoneyType' newBalance: $ref: '#/definitions/MoneyType' payerNote: type: string description: A descriptive note for sender transaction history. example: Manual Boost for RWC status: type: string description: Status of the payment method. example: Approved correlatorId: type: string description: Unique identifier in the client for the payment in case it is needed to correlate. example: c5f80cb8-dc8b-11ea-87d0-0242ac130003 statusDate: type: string description: Time the status of the payment changed. example: '2020-08-12T11:04:53.668Z' additionalInformation: $ref: '#/definitions/AdditionalInformation' metaData: $ref: '#/definitions/MetaData' loyaltyInformation: $ref: '#/definitions/LoyaltyBalances' externalCode: type: string description: This is the external reference code. This can be the bank institution code for the NIMBS payments usecases PaymentTransactionStatusData: type: object properties: financialTransactionId: type: string description: The financial transaction ID. Generated by the back-end system. status: type: string description: Payment Status. example: Approved requestType: type: string description: Request Type. fulfillmentStatus: type: string description: The financial transaction fullfilment status. transactionRefParent: type: string description: The financial transaction reference parent. transactionDescription: type: string description: The financial transaction description. amount: type: number description: The financial transactional amount. example: 3453.45 date: type: string description: payment date example: "2021-11-21T15:39:33.8838432+01:00" channel: type: string description: Channel of the payment request eg. USSD example: "USSD" product: type: string description: A product id, name etc. example: "122309940" description: type: string description: can be a payer note, a merchant identifier ie. merchantId etc. customer: $ref: '#/definitions/CustomerObject' charges: $ref: '#/definitions/ChargesObject' ChargesObject: type: object description: "Total charges associated with a particular payment" properties: amount: type: number example: 90.99 payer: type: string description: the bearer of the payment charges ie. [Merchant, Customer] enum: - M - C CustomerObject: type: object properties: firstname: type: string description: Customer First Name. example: John surname: type: string description: Customer surname. example: Doe email: type: string description: Customer email. example: johndoe@email.com msisdn: type: string description: Customer Mobile number. example: '263897646890' AdditionalInfoObject: type: object properties: name: type: string description: Product Name. example: Product A description: type: string description: Product Identifier. example: Prod_2349 DetailsObject: type: object properties: brand: type: string description: Telco Code. example: AB233 fulfillmentMsisdn: type: string description: Fulfillment Msisdn. example: '263897646890' issuer: type: string description: Source of funds scheme. example: 'VISA' PaymentTransactionStatusResponse: type: object properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '0000' statusMessage: type: string description: 'This is a description of the status' correlatorId: type: string description: Unique identifier in the client for the payment in case it is needed to correlate, a trace id associated with the caller customerId: type: string description: Customer identifier, a terminal id etc. example: "231167543AR2" sequenceNo: type: string description: A unique id for tracing all requests example: 12345 providerTransactionId: type: string example: FT172145YB21 description: 'ID of the payment, generated by back-end system. This can be blank if the payment has previously been pre-approved.' data: $ref: '#/definitions/PaymentTransactionStatusData' additionalInformation: $ref: '#/definitions/AdditionalInfoObject' details: $ref: '#/definitions/DetailsObject' _links: $ref: '#/definitions/PaymentTransactionStatusResponse__Links' PaymentTransactionStatusResponse__Links_Self: type: object properties: href: type: string example: 'https://host:port/payments/v1/12345' description: Hyperlink to access the financial payment transaction status. PaymentTransactionStatusResponse__Links: type: object properties: self: $ref: '#/definitions/PaymentTransactionStatusResponse__Links_Self' description: Relevant links to the financial payment transaction status. promiseToPayRequest: description: Payment Request details. type: object properties: billingAccountNo: type: string description: Unique Billing Account number of the customer example: 903442299RC serviceName: type: string description: Service name of the payment. example: Outstanding Dues promiseOpenDate: type: string format: date-time description: Start Date of the Promise. example: '2020-08-12T11:04:53.668Z' promiseAmount: type: number format: double description: Amount promised to be paid. example: 1290.00 numberOfInstallments: type: string description: Number of the EMI. example: 3 durationUOM: type: string description: Unit of Measure for the EMI (can be Month, Week and Year). example: 'Month' promiseThreshold: type: string description: The Promise Threshold example: 100 promiseToPayResponse: description: Promise details response type: object properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '0000' statusMessage: type: string description: Message of the transaction. Either Success or Failure. transactionId: type: string description: Unique identifier for every request to the backend. Mapped from input request. example: 5345345 sequenceNo: type: string description: A unique id for tracing all requests example: 12345 data: type: object properties: PromiseDetails: type: array items: $ref: '#/definitions/PromiseDetail' _links: $ref: '#/definitions/Response_Links' Response_Links: type: object properties: self: $ref: '#/definitions/Response_Links_Self' Response_Links_Self: type: object properties: href: type: string example: 'https://host:port/payments/payment-agreement/' description: Hyperlink to access the payment agreement generation endpoint. PromiseDetail: type: object properties: installmentDueAmount: type: string example: 266.67 description: Installment Amount Due to be paid installmentEndDate: type: string format: date-time description: End date of Installment example: '2020-08-12T11:04:53.668Z' queryNumber: type: string example: FT172145YB21 description: Query Number in SV installmentStartDate: type: string format: date-time description: Start Date of Installment example: '2020-08-12T11:04:53.668Z' PaymentHistoryResponse: type: object description: >- The Payment resource represents a performed payment. It contains both information about the payment and the payment method used to perform it. required: - account - paymentMethod properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '0000' statusMessage: type: string description: Message of the transaction. Either Success or Failure. transactionId: type: string description: Unique identifier for every request to the backend. Mapped from input request. example: 5345345 customerId: type: string description: Customer Id of the customer whose history is being retrieved sequenceNo: type: string description: A unique id for tracing all requests example: 12345 data: type: object properties: id: type: string description: Unique identifier of Payment href: type: string description: Hypertext Reference of the Payment authorizationCode: type: string description: >- Authorization code retrieved from an external payment gateway that could be used for conciliation correlatorId: type: string description: >- Unique identifier in the client for the payment in case it is needed to correlate description: type: string description: Text describing the contents of the payment name: type: string description: Screen name of the payment paymentDate: type: string format: date-time description: Date when the payment was performed status: type: string description: Status of the payment statusDate: type: string format: date-time description: Date when the status was recorded account: $ref: '#/definitions/AccountRef' amount: $ref: '#/definitions/Money' description: Amount to be paid (net of taxes) relatedParty: $ref: '#/definitions/RelatedParty' payer: $ref: '#/definitions/RelatedParty' paymentItem: type: array items: $ref: '#/definitions/PaymentItem' totalAmount: $ref: '#/definitions/Money' description: Amount to be paid (including taxes) 'type': type: string description: When sub-classing, this defines the sub-class entity name callbackUrl: type: string description: Callback URL paymentRecords: type: array items: $ref: '#/definitions/PaymentRecord' TimePeriod: type: object description: >- A period of time, either as a deadline (endDateTime only) a startDateTime only, or both properties: endDateTime: type: string format: date-time description: End of the time period, using IETC-RFC-3339 format startDateTime: type: string format: date-time description: >- Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end Money: type: object description: A base / value business entity used to represent money properties: unit: type: string description: Currency (ISO4217 norm uses 3 letters to define the currency) value: type: number format: float description: A positive floating point number PaymentRecord: type: object properties: paymentDate: type: string description: type: string status: type: string fulfillmentStatus: type: string details: type: object properties: brand: type: string issuer: type: string paymentId: type: string paymentType: type: string commitDate: type: string fxRate: type: string initiatingUser: type: string realUser: type: string initiatingAccountHolder: type: string realAccountHolder: type: string originator: type: string originatorAccount: type: string mainInstructionId: type: string instructionId: type: string transactionId: type: string destinationAccountHolder: type: string originatorFirstName: type: string originatorLastName: type: string originatorHandlerFirstName: type: string originatorHandlerLastName: type: string destinationFirstName: type: string destinationLastName: type: string destinationHandlerFirstName: type: string destinationHandlerLastName: type: string channel: type: string originatorAccountHolder: type: string destination: type: string destinationAccount: type: string originatorAmount: type: object properties: amount: type: string unit: type: string originatorFee: type: object properties: amount: type: string unit: type: string originalAmount: type: object properties: amount: type: string unit: type: string amount: type: object properties: amount: type: string unit: type: string destinationAmount: type: object properties: amount: type: string unit: type: string destinationFee: type: object properties: amount: type: string unit: type: string destinationAvailableBalance: type: object properties: amount: type: string unit: type: string destinationTotalBalance: type: object properties: amount: type: string unit: type: string destinationCommittedBalance: type: object properties: amount: type: string unit: type: string RelatedParty: type: object description: >- Related Entity reference. A related party defines party or party role linked to a specific entity. properties: id: type: string description: Unique identifier of a related entity. name: type: string description: Name of the related entity. otherName: type: string description: Othername of the related party entity email: type: string description: Email of the related party entity validFor: $ref: '#/definitions/TimePeriod' PaymentItem: type: object properties: id: type: string description: Unique identifier of the payment Item item: type: object properties: id: type: string description: ID of the item being paid for. This can be a productId name: type: string description: This is the name of the item being paid for AccountRef: type: object properties: id: type: string description: Unique identifier of the account description: type: string description: Detailed description of the account name: type: string description: Name of the account ReverseTransactionHistory: type: object properties: statusCode: type: string example: '0000' statusMessage: type: string example: 'success' transactionId: type: string description: "API generated Id to include for tracing requests" correlatorId: type: string sequenceNo: type: string description: A unique id for tracing all requests example: 12345 data: $ref: '#/definitions/ReverseTransactionHistoryData' loyaltyInformation: $ref: "#/definitions/LoyaltyBalances" _links: $ref: '#/definitions/PaymentResponse__Links' ReverseTransactionHistoryData: type: object properties: transactionstatus: type: string description: SUCCESSFULL. transfertype: type: string description: TRANSFER. startdate: type: string description: Select transactions starting from this date and time. commitdate: type: string description: The date and time at which the transaction was completed. fxrate: type: string description: The foreign exchange rate. externalfxrate: type: string description: The external foreign exchange rate in an interoperability transfer. initiatinguser: type: string description: The execution ID of the user that initiated the transaction. realuser: type: string description: The execution ID of the real user that initiated the transaction. reviewinguser: type: string description: The execution ID of the user that reviewed the transaction. initiatingaccountholder: type: string description: The Identity of the account holder that initiated the transaction if it was initiated by an account holder. realaccountholder: type: string description: The Identity of the real account holder that is effected by the transaction if it was initiated by an account holder. providercategory: type: string description: The name of the provider category. from: type: string description: The sending user's default FRI. fromaccount: type: string description: The sending account FRI. fromamount: $ref: '#/definitions/MoneyCurrencyType' fromfee: $ref: '#/definitions/MoneyCurrencyType' fromexternalfee: $ref: '#/definitions/MoneyCurrencyType' fromdiscount: $ref: '#/definitions/MoneyCurrencyType' frompromotion: $ref: '#/definitions/MoneyCurrencyType' fromloyfee: $ref: '#/definitions/MoneyCurrencyType' fromloyreward: $ref: '#/definitions/MoneyCurrencyType' frompromotionrefund: $ref: '#/definitions/MoneyCurrencyType' fromnote: type: string description: The sender's note.. fromavailablebalance: $ref: '#/definitions/MoneyCurrencyType' fromtotalbalance: $ref: '#/definitions/MoneyCurrencyType' fromcommittedbalance: $ref: '#/definitions/MoneyCurrencyType' fromaccountholder: type: string description: The identity of the sending account holder. originalamount: $ref: '#/definitions/MoneyCurrencyType' externalamount: $ref: '#/definitions/MoneyCurrencyType' amount: $ref: '#/definitions/MoneyCurrencyType' fromcouponvalue: $ref: '#/definitions/MoneyCurrencyType' fromtaxes: $ref: '#/definitions/MoneyCurrencyType' fromtaxesrefund: $ref: '#/definitions/MoneyCurrencyType' to: type: string description: The receiving user's FRI or the receiving account's FRI. toaccount: type: string description: The receiving account's FRI. toamount: $ref: '#/definitions/MoneyCurrencyType' tofee: $ref: '#/definitions/MoneyCurrencyType' toexternalfee: $ref: '#/definitions/MoneyCurrencyType' topromotion: $ref: '#/definitions/MoneyCurrencyType' toloyfee: $ref: '#/definitions/MoneyCurrencyType' toloyreward: $ref: '#/definitions/MoneyCurrencyType' topromotionrefund: $ref: '#/definitions/MoneyCurrencyType' todiscountrefund: $ref: '#/definitions/MoneyCurrencyType' tomessage: type: string description: The receiver's message. toavailablebalance: $ref: '#/definitions/MoneyCurrencyType' tototalbalance: $ref: '#/definitions/MoneyCurrencyType' tocommittedbalance: $ref: '#/definitions/MoneyCurrencyType' maininstructionid: type: string description: The main instruction ID. instructionid: type: string description: The financial instruction ID.. externaltransactionid: type: string description: External transaction ID for the operation.. transactiontext: type: string description: Text describing the transaction.. tofeerefund: $ref: '#/definitions/MoneyCurrencyType' fromfeerefund: $ref: '#/definitions/MoneyCurrencyType' toaccountholder: type: string description: The Identity of the receiving account holder. totaxes: $ref: '#/definitions/MoneyCurrencyType' totaxesrefund: $ref: '#/definitions/MoneyCurrencyType' fromfirstname: type: string description: The first name of the sender. fromlastname: type: string description: The last name of the sender. fromhandlerfirstname: type: string description: The first name of the handler on the sender side. fromhandlerlastname: type: string description: The last name of the handler on the sender side. tofirstname: type: string description: The first name of receiver. tolastname: type: string description: The last name of the receiver. tohandlerfirstname: type: string description: The first name of the handler on the receiver side. tohandlerlastname: type: string description: The last name of the handler on the receiver side. fromposmsisdn: type: string description: The point of sale msisdn of the sender. toposmsisdn: type: string description: The point of sale msisdn of the receiver. originaltransactionid: type: string description: The original transaction id.. communicationchannel: type: string description: The communication channel.. externalserviceprovider: type: string description: The external service provider that was involved in the transaction.. externalSvcPrdTranId: type: string description: The transaction ID generated by an external service provider. This field is only available when searching for a specific transaction by financialTransactionId or externalTransactionId. fromExInstruProvTransId: type: string description: The external transaction identifier as provided by the external instrument provider if the sending FRI is an external instrument. This field is only available when searching for a specific transaction by financialTransactionId or externalTransactionId.. toExInstruProvTransId: type: string description: The external transaction identifier as provided by the external instrument provider if the receiving FRI is an external instrument. This field is only available when searching for a specific transaction by financialTransactionId or externalTransactionId. fromExInstruAccHolder: type: string description: The external instrument provider account holder if the sending FRI is an external instrument. This field is only available when searching for a specific transaction by financialTransactionId or externalTransactionId. toExInstruAccHolder: type: string description: The external instrument provider account holder if the receiving FRI is an external instrument. This field is only available when searching for a specific transaction by financialTransactionId or externalTransactionId. fitype: type: string description: Shows the financial transaction type. FeecheckRequest: description: Payment Request details. type: object properties: correlatorId: type: string description: Unique identifier in the client for the payment in case it is needed to correlate, a trace id associated with the caller example: c5f80cb8-dc8b-11ea-87d0-0242ac130003 paymentDate: type: string format: date-time description: Date when the payment was performed. example: '2020-08-12T11:04:53.668Z' name: type: string description: Screen name of the payment. example: Manual Boost for RWC callingSystem: type: string description: calling system. example: 'AYOBA' transactionType: type: string description: calling systemn. example: 'FeeCheck' targetSystem: type: string description: calling systemn. example: 'ECW' callbackURL: type: string description: The callback URL. example: 'https://api.mtn.com/v1/callback' quoteId: type: string description: The ID of the quote used, a terminal id associated with the caller. example: '9223372036854775807' channel: type: string description: The channel used to perform the payment operation or just the channel itself with just its name. example: AIRTIME description: type: string description: Text describing the contents of the payment. example: Manual Boost for RW authorizationCode: type: string description: Authorization code retrieved from an external payment gateway that could be used for conciliation. example: feeBearer: type: string description: Who bears a charge for a particular transaction , whether a Payer or Payee enum: - Payer - Payee amount: $ref: '#/definitions/FeeMoneyType' taxAmount: $ref: '#/definitions/FeeMoneyType' totalAmount: $ref: '#/definitions/FeeMoneyType' payer: $ref: '#/definitions/Payer' payee: type: array items: $ref: '#/definitions/Payee' paymentMethod: $ref: '#/definitions/PaymentMethod' status: type: string description: Status of the payment method. example: Pending statusDate: type: string format: date-time description: Time the status of the payment method changed. example: '2020-08-12T11:04:53.668Z' additionalInformation: type: array items: $ref: '#/definitions/AdditionalInformation' segment: type: string description: Segment of the customer. Forexample, subscriber,agent, merchant, admin depending on the type of customer whome the operation is being performed against. enum: [subscriber,agent, merchant, admin] required: - totalAmount - paymentMethod - correlatorId - transactionType - countryCode - callbackURL FeeMoneyType: description: Representation of SWZ monetary value. type: object properties: amount: format: decimal type: number description: Amount of money example: 50 units: type: string description: Currency example: SWZ required: - amount - units InboundResponse: type: object required: - statusCode - error - data - senderfee properties: statusCode: type: string description: "This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' " example: "0000" error: type: string example: "null" sequenceNo: type: string description: A unique id for tracing all requests example: 12345 data: type: "object" properties: statusCode: type: string description: "message" example: "SUCCESSFUL" providerTransactionId: type: string example: "3394844" statusMessage: type: string example: "success" feeDetails: type: "array" items: $ref: "#/definitions/feeElements" feeElements: type: object required: - quoteId - fees - feeFri properties: quoteId: type: string description: "427842" fees: type: "object" required: - amount properties: amount: type: string description: "transfered amount" example: "1000.00" units: type: string example: "SZL" feeFri: type: string example: "FRI:26876700060/MSISDN" BadFeeRequest: type: object properties: timestamp: type: string format: date-time description: Timestamp that the error occurred example: '2021-07-21T17:32:28Z' status: type: string description: "Http status" example: "400" error: type: string description: "error message" example: "Bad Request" message: type: string description: "error message" sequenceNo: type: string description: A unique id for tracing all requests example: 12345 path: type: string description: The path that caused the error example: /payments/fee FeeRequestNotFound: type: object properties: timestamp: type: string format: date-time description: Timestamp that the error occurred example: '2021-07-21T17:32:28Z' status: type: string description: "Http status" example: "500" error: type: string description: "error message" example: "Internal Server Error" message: type: string description: "error message" sequenceNo: type: string description: A unique id for tracing all requests example: 12345 path: type: string description: The path that caused the error example: /payments/fee promiseToPayEligibilityResponse: description: Promise details response type: object properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '0000' statusMessage: type: string description: Message of the transaction. Either Success or Failure. transactionId: type: string description: Unique identifier for every request to the backend. Mapped from input request. example: 5345345 data: type: object properties: PromiseToPayEligibilityDetails: $ref: '#/definitions/promiseToPayEligibility' promiseToPayEligibility: description: Payment Request eligibility details. type: object properties: eligibilityStatus: type: string description: Promise to pay eligibility status. Possible status values are ‘Eligible’, ‘Not-eligible’. example: Eligible accountBalance: type: string description: Entire Outstanding amount of the account example: 9274 minimumAmount: type: string description: Applies NRT_THRESHOLD_VALUE on account balance and returns as the minimumAmount example: 1000 paymentStartDate: type: string description: Payment Start Date holds API triggered date (DD-MM-YYYY) example: 17-10-2022 Error: type: object required: - statusCode - statusMessage properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '1000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client supportMessage: type: string description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful) transactionId: type: string description: This is the same transactionId that is sent in the request example: cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4 timestamp: type: string format: date-time description: Timestamp that the error occurred example: '2021-07-21T17:32:28Z' sequenceNo: type: string description: A unique id for tracing all requests example: 12345 path: type: string description: The path that caused the error example: /subscribers/27831234567 method: type: string description: The HTTP method type that was used example: GET