{
"openapi": "3.0.1",
"info": {
"title": "Collection",
"description": "Partner Gateway API document",
"version": "1.0"
},
"servers": [
{
"url": "https://sandbox.momodeveloper.mtn.co.rw/collection"
}
],
"paths": {
"/token/": {
"post": {
"summary": "/token - POST",
"description": "This operation is used to create an access token which can then be used to authorize and authenticate towards the other end-points of the API.",
"operationId": "token-POST",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Basic authentication header containing API user ID and API key. Should be sent in as B64 encoded.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenPost200ApplicationJsonResponse"
},
"example": {
"access_token": "string",
"token_type": "string",
"expires_in": 0
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenPost401ApplicationJsonResponse"
},
"example": {
"error": "string"
}
}
}
},
"500": {
"description": "Error",
"content": {
"application/json": { }
}
}
}
}
},
"/v1_0/account/balance": {
"get": {
"summary": "/v1_0/account/balance - GET",
"description": "Get the balance of the account.",
"operationId": "get-v1_0-account-balance",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Authorization header used for Basic authentication and oauth. Format of the header parameter follows the standard for Basic and Bearer. Oauth uses Bearer authentication type where the credential is the received access token.",
"schema": {
"type": "string"
}
},
{
"name": "X-Target-Environment",
"in": "header",
"description": "The identifier of the EWP system where the transaction shall be processed. This parameter is used to route the request to the EWP system that will initiate the transaction.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Ok",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Balance"
},
"example": {
"availableBalance": "string",
"currency": "string"
}
},
"Incorrect target environment": {
"schema": {
"$ref": "#/components/schemas/Balance"
}
}
}
},
"400": {
"description": "Bad request, e.g. invalid data was sent in the request.",
"content": {
"application/json": { },
"Incorrect target environment": { }
}
},
"500": {
"description": "Internal error. The returned response contains details.",
"content": {
"Incorrect target environment": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "NOT_ALLOWED_TARGET_ENVIRONMENT",
"message": "Access to target environment is forbidden."
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "PAYEE_NOT_FOUND",
"message": "string"
}
}
}
}
}
}
},
"/v1_0/accountholder/{accountHolderIdType}/{accountHolderId}/active": {
"get": {
"summary": "/v1_0/accountholder/{accountHolderIdType}/{accountHolderId}/active - GET",
"description": "Operation is used to check if an account holder is registered and active in the system.",
"operationId": "get-v1_0-accountholder-accountholderidtype-accountholderid-active",
"parameters": [
{
"name": "accountHolderId",
"in": "path",
"description": "The party number. Validated according to the party ID type (case Sensitive).
msisdn - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
email - Validated to be a valid e-mail format. Validated with IsEmail
party_code - UUID of the party. Validated with IsUuid",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "accountHolderIdType",
"in": "path",
"description": "Specifies the type of the party ID. Allowed values [msisdn, email, party_code].
accountHolderId should explicitly be in small letters.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "Authorization header used for Basic authentication and oauth. Format of the header parameter follows the standard for Basic and Bearer. Oauth uses Bearer authentication type where the credential is the received access token.",
"schema": {
"type": "string"
}
},
{
"name": "X-Target-Environment",
"in": "header",
"description": "The identifier of the EWP system where the transaction shall be processed. This parameter is used to route the request to the EWP system that will initiate the transaction.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Ok. True if account holder is registered and active, false if the account holder is not active or not found",
"content": {
"Incorrect target environment": { }
}
},
"400": {
"description": "Bad request, e.g. invalid data was sent in the request.",
"content": {
"Incorrect target environment": { }
}
},
"500": {
"description": "Internal error. The returned response contains details.",
"content": {
"Incorrect target environment": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "NOT_ALLOWED_TARGET_ENVIRONMENT",
"message": "Access to target environment is forbidden."
}
}
}
}
}
}
},
"/v1_0/requesttopay": {
"post": {
"summary": "/requesttopay - POST",
"description": "This operation is used to request a payment from a consumer (Payer). The payer will be asked to authorize the payment. The transaction will be executed once the payer has authorized the payment. The requesttopay will be in status PENDING until the transaction is authorized or declined by the payer or it is timed out by the system. \n Status of the transaction can be validated by using the GET /requesttopay/\\",
"operationId": "requesttopay-POST",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Authorization header used for Basic authentication and oauth. Format of the header parameter follows the standard for Basic and Bearer. Oauth uses Bearer authentication type where the credential is the received access token.",
"schema": {
"type": "string"
}
},
{
"name": "X-Callback-Url",
"in": "header",
"description": "URL to the server where the callback should be sent.",
"schema": {
"type": "string"
}
},
{
"name": "X-Reference-Id",
"in": "header",
"description": "Format - UUID. Recource ID of the created request to pay transaction. This ID is used, for example, validating the status of the request. ‘Universal Unique ID’ for the transaction generated using UUID version 4.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Target-Environment",
"in": "header",
"description": "The identifier of the EWP system where the transaction shall be processed. This parameter is used to route the request to the EWP system that will initiate the transaction.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestToPay"
},
"example": {
"amount": "string",
"currency": "string",
"externalId": "string",
"payer": {
"partyIdType": "MSISDN",
"partyId": "string"
},
"payerMessage": "string",
"payeeNote": "string"
}
}
}
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": { },
"ReferenceId already in use": { },
"Unspecified internal error": { }
}
},
"400": {
"description": "Bad request, e.g. invalid data was sent in the request.",
"content": {
"application/json": { },
"ReferenceId already in use": { },
"Unspecified internal error": { }
}
},
"409": {
"description": "Conflict, duplicated reference id",
"content": {
"ReferenceId already in use": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "RESOURCE_ALREADY_EXIST",
"message": "Duplicated reference id. Creation of resource failed."
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "PAYEE_NOT_FOUND",
"message": "string"
}
},
"Unspecified internal error": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
}
}
}
},
"500": {
"description": "Internal Error.",
"content": {
"Unspecified internal error": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "INTERNAL_PROCESSING_ERROR",
"message": "An internal error occurred while processing."
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "PAYEE_NOT_FOUND",
"message": "string"
}
},
"ReferenceId already in use": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
}
}
}
}
}
}
},
"/v1_0/requesttopay/{referenceId}": {
"get": {
"summary": "/requesttopay/{referenceId} - GET",
"description": "This operation is used to get the status of a request to pay. X-Reference-Id that was passed in the post is used as reference to the request.",
"operationId": "requesttopay-referenceId-GET",
"parameters": [
{
"name": "referenceId",
"in": "path",
"description": "UUID of transaction to get result. Reference id used when creating the request to pay.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "Authorization header used for Basic authentication and oauth. Format of the header parameter follows the standard for Basic and Bearer. Oauth uses Bearer authentication type where the credential is the received access token.",
"schema": {
"type": "string"
}
},
{
"name": "X-Target-Environment",
"in": "header",
"description": "The identifier of the EWP system where the transaction shall be processed. This parameter is used to route the request to the EWP system that will initiate the transaction.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK. Note that a failed request to pay will be returned with this status too. The 'status' of the RequestToPayResult can be used to determine the outcome of the request. The 'reason' field can be used to retrieve a cause in case of failure.",
"content": {
"Successful request to pay": {
"schema": {
"$ref": "#/components/schemas/RequestToPayResult"
},
"example": {
"amount": 100,
"currency": "UGX",
"financialTransactionId": 23503452,
"externalId": 947354,
"payer": {
"partyIdType": "MSISDN",
"partyId": 4656473839
},
"status": "SUCCESSFUL"
}
},
"Payer not found": {
"schema": {
"$ref": "#/components/schemas/RequestToPayResult"
},
"example": {
"amount": 100,
"currency": "UGX",
"externalId": 947354,
"payer": {
"partyIdType": "MSISDN",
"partyId": 4656473839
},
"status": "FAILED",
"reason": {
"code": "PAYER_NOT_FOUND",
"message": "Payee does not exist"
}
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestToPayResult"
},
"example": {
"amount": "string",
"currency": "string",
"financialTransactionId": "string",
"externalId": "string",
"payer": {
"partyIdType": "MSISDN",
"partyId": "string"
},
"payerMessage": "string",
"payeeNote": "string",
"status": "PENDING",
"reason": {
"code": "PAYEE_NOT_FOUND",
"message": "string"
}
}
},
"Request to pay not found": {
"schema": {
"$ref": "#/components/schemas/RequestToPayResult"
}
},
"Unspecified internal error": {
"schema": {
"$ref": "#/components/schemas/RequestToPayResult"
}
}
}
},
"400": {
"description": "Bad request, e.g. an incorrectly formatted reference id was provided.",
"content": {
"Successful request to pay": { },
"Payer not found": { },
"application/json": { },
"Request to pay not found": { },
"Unspecified internal error": { }
}
},
"404": {
"description": "Resource not found.",
"content": {
"Request to pay not found": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "RESOURCE_NOT_FOUND",
"message": "Requested resource was not found."
}
},
"Successful request to pay": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
}
},
"Payer not found": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "PAYEE_NOT_FOUND",
"message": "string"
}
},
"Unspecified internal error": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
}
}
}
},
"500": {
"description": "Internal Error. Note that if the retrieved request to pay has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.",
"content": {
"Unspecified internal error": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "INTERNAL_PROCESSING_ERROR",
"message": "An internal error occurred while processing."
}
},
"Successful request to pay": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
}
},
"Payer not found": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
},
"example": {
"code": "PAYEE_NOT_FOUND",
"message": "string"
}
},
"Request to pay not found": {
"schema": {
"$ref": "#/components/schemas/ErrorReason"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"TokenPost200ApplicationJsonResponse": {
"type": "object",
"properties": {
"access_token": {
"type": "string",
"description": "A JWT token which can be used to authrize against the other API end-points. The format of the token follows the JWT standard format (see jwt.io for an example). This is the token that should be sent in in the Authorization header when calling the other API end-points."
},
"token_type": {
"type": "string",
"description": "The token type."
},
"expires_in": {
"type": "integer",
"description": "The validity time in seconds of the token."
}
}
},
"TokenPost401ApplicationJsonResponse": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "An error code."
}
}
},
"Balance": {
"type": "object",
"properties": {
"availableBalance": {
"type": "string",
"description": "The available balance of the account"
},
"currency": {
"type": "string",
"description": "ISO4217 Currency"
}
},
"description": "The available balance of the account"
},
"Party": {
"type": "object",
"properties": {
"partyIdType": {
"enum": [
"MSISDN",
"EMAIL",
"PARTY_CODE"
],
"type": "string"
},
"partyId": {
"type": "string"
}
},
"description": "Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId
MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN
EMAIL - Validated to be a valid e-mail format. Validated with IsEmail
PARTY_CODE - UUID of the party. Validated with IsUuid"
},
"PreApproval": {
"type": "object",
"properties": {
"payer": {
"$ref": "#/components/schemas/Party"
},
"payerCurrency": {
"type": "string",
"description": "ISO4217 Currency"
},
"payerMessage": {
"type": "string",
"description": "The mesage that is shown to the approver."
},
"validityTime": {
"type": "integer",
"description": "The request validity time of the pre-approval"
}
}
},
"PreApprovalResult": {
"type": "object",
"properties": {
"payer": {
"$ref": "#/components/schemas/Party"
},
"payerCurrency": {
"type": "string",
"description": "ISO4217 Currency"
},
"payerMessage": {
"type": "string",
"description": "The mesage that is shown to the approver."
},
"validityTime": {
"type": "integer",
"description": "The request validity time of the pre-approval"
},
"status": {
"enum": [
"PENDING",
"SUCCESSFUL",
"FAILED"
],
"type": "string"
},
"reason": {
"$ref": "#/components/schemas/ErrorReason"
}
}
},
"RequestToPay": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Amount that will be debited from the payer account."
},
"currency": {
"type": "string",
"description": "ISO4217 Currency"
},
"externalId": {
"type": "string",
"description": "External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique."
},
"payer": {
"$ref": "#/components/schemas/Party"
},
"payerMessage": {
"type": "string",
"description": "Message that will be written in the payer transaction history message field."
},
"payeeNote": {
"type": "string",
"description": "Message that will be written in the payee transaction history note field."
}
}
},
"RequestToPayResult": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Amount that will be debited from the payer account."
},
"currency": {
"type": "string",
"description": "ISO4217 Currency"
},
"financialTransactionId": {
"type": "string",
"description": "Financial transactionIdd from mobile money manager.
Used to connect to the specific financial transaction made in the account"
},
"externalId": {
"type": "string",
"description": "External id provided in the creation of the requestToPay transaction."
},
"payer": {
"$ref": "#/components/schemas/Party"
},
"payerMessage": {
"type": "string",
"description": "Message that will be written in the payer transaction history message field."
},
"payeeNote": {
"type": "string",
"description": "Message that will be written in the payee transaction history note field."
},
"status": {
"enum": [
"PENDING",
"SUCCESSFUL",
"FAILED"
],
"type": "string"
},
"reason": {
"$ref": "#/components/schemas/ErrorReason"
}
}
},
"Transfer": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Amount that will be debited from the payer account."
},
"currency": {
"type": "string",
"description": "ISO4217 Currency"
},
"externalId": {
"type": "string",
"description": "External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique."
},
"payee": {
"$ref": "#/components/schemas/Party"
},
"payerMessage": {
"type": "string",
"description": "Message that will be written in the payer transaction history message field."
},
"payeeNote": {
"type": "string",
"description": "Message that will be written in the payee transaction history note field."
}
}
},
"TransferResult": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Amount that will be debited from the payer account."
},
"currency": {
"type": "string",
"description": "ISO4217 Currency"
},
"financialTransactionId": {
"type": "string",
"description": "Financial transactionIdd from mobile money manager.
Used to connect to the specific financial transaction made in the account"
},
"externalId": {
"type": "string",
"description": "External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report.
External id is not required to be unique."
},
"payee": {
"$ref": "#/components/schemas/Party"
},
"payerMessage": {
"type": "string",
"description": "Message that will be written in the payer transaction history message field."
},
"payeeNote": {
"type": "string",
"description": "Message that will be written in the payee transaction history note field."
},
"status": {
"enum": [
"PENDING",
"SUCCESSFUL",
"FAILED"
],
"type": "string"
},
"reason": {
"$ref": "#/components/schemas/ErrorReason"
}
}
},
"ErrorReason": {
"type": "object",
"properties": {
"code": {
"enum": [
"PAYEE_NOT_FOUND",
"PAYER_NOT_FOUND",
"NOT_ALLOWED",
"NOT_ALLOWED_TARGET_ENVIRONMENT",
"INVALID_CALLBACK_URL_HOST",
"INVALID_CURRENCY",
"SERVICE_UNAVAILABLE",
"INTERNAL_PROCESSING_ERROR",
"NOT_ENOUGH_FUNDS",
"PAYER_LIMIT_REACHED",
"PAYEE_NOT_ALLOWED_TO_RECEIVE",
"PAYMENT_NOT_APPROVED",
"RESOURCE_NOT_FOUND",
"APPROVAL_REJECTED",
"EXPIRED",
"TRANSACTION_CANCELED",
"RESOURCE_ALREADY_EXIST"
],
"type": "string"
},
"message": {
"type": "string"
}
}
},
"BooleanResult": {
"type": "object",
"properties": {
"result": {
"type": "boolean"
}
}
}
},
"securitySchemes": {
"apiKeyHeader": {
"type": "apiKey",
"name": "Ocp-Apim-Subscription-Key",
"in": "header"
},
"apiKeyQuery": {
"type": "apiKey",
"name": "subscription-key",
"in": "query"
}
}
},
"security": [
{
"apiKeyHeader": [ ]
},
{
"apiKeyQuery": [ ]
}
]
}