{
"swagger": "2.0",
"info": {
"title": "Remittance",
"version": "1.0",
"description": "Partner Gateway API document"
},
"host": "proxy.momoapi.mtn.co.rw",
"basePath": "/remittance",
"schemes": [
"https"
],
"securityDefinitions": {
"apiKeyHeader": {
"type": "apiKey",
"name": "Ocp-Apim-Subscription-Key",
"in": "header"
},
"apiKeyQuery": {
"type": "apiKey",
"name": "subscription-key",
"in": "query"
}
},
"security": [
{
"apiKeyHeader": []
},
{
"apiKeyQuery": []
}
],
"paths": {
"/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",
"summary": "/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,
"type": "string"
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/TokenPost200ApplicationJsonResponse"
},
"examples": {
"application/json": "{\r\n \"access_token\": \"string\",\r\n \"token_type\": \"string\",\r\n \"expires_in\": 0\r\n}"
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/TokenPost401ApplicationJsonResponse"
},
"examples": {
"application/json": "{\r\n \"error\": \"string\"\r\n}"
}
},
"500": {
"description": "Error"
}
}
}
},
"/v1_0/account/balance": {
"get": {
"description": "Get the balance of the account.",
"operationId": "get-v1_0-account-balance",
"summary": "/v1_0/account/balance - GET",
"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.",
"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,
"type": "string"
}
],
"produces": [
"application/json",
"Incorrect target environment"
],
"responses": {
"200": {
"description": "Ok",
"schema": {
"$ref": "#/definitions/Balance"
},
"examples": {
"application/json": "{\r\n \"availableBalance\": \"string\",\r\n \"currency\": \"string\"\r\n}"
}
},
"400": {
"description": "Bad request, e.g. invalid data was sent in the request."
},
"500": {
"description": "Internal error. The returned response contains details.",
"schema": {
"$ref": "#/definitions/ErrorReason"
},
"examples": {
"Incorrect target environment": "{\r\n \"code\": \"NOT_ALLOWED_TARGET_ENVIRONMENT\",\r\n \"message\": \"Access to target environment is forbidden.\"\r\n}",
"application/json": "{\r\n \"code\": \"PAYEE_NOT_FOUND\",\r\n \"message\": \"string\"\r\n}"
}
}
}
}
},
"/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",
"summary": "/v1_0/accountholder/{accountHolderIdType}/{accountHolderId}/active - GET",
"parameters": [
{
"name": "accountHolderId",
"in": "path",
"description": "The party number. Validated according to the party id type.
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,
"type": "string"
},
{
"name": "accountHolderIdType",
"in": "path",
"description": "Specifies the type of the party id. Allowed values [msisdn, email, party_code].",
"required": true,
"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.",
"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,
"type": "string"
}
],
"produces": [
"Incorrect target environment"
],
"responses": {
"200": {
"description": "Ok. True if account holder is registered and active, false if the account holder is not active or not found found"
},
"400": {
"description": "Bad request, e.g. invalid data was sent in the request."
},
"500": {
"description": "Internal error. The returned response contains details.",
"schema": {
"$ref": "#/definitions/ErrorReason"
},
"examples": {
"Incorrect target environment": "{\r\n \"code\": \"NOT_ALLOWED_TARGET_ENVIRONMENT\",\r\n \"message\": \"Access to target environment is forbidden.\"\r\n}"
}
}
}
}
},
"/v1_0/transfer": {
"post": {
"description": "Transfer operation is used to transfer an amount from the own account to a payee account.
Status of the transaction can validated by using the GET /transfer/\\{referenceId\\}",
"operationId": "transfer-POST",
"summary": "/transfer - 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.",
"type": "string"
},
{
"name": "X-Callback-Url",
"in": "header",
"description": "URL to the server where the callback should be sent.",
"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 e.g. validating the status of the request. Universal unique id for the transaction generated using UUID version 4.",
"required": true,
"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,
"type": "string"
},
{
"name": "transfer",
"in": "body",
"schema": {
"$ref": "#/definitions/Transfer"
}
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json",
"ReferenceId already in use",
"Incorrect currency for target environment"
],
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"description": "Bad request, e.g. invalid data was sent in the request."
},
"409": {
"description": "Conflict, duplicated reference id",
"schema": {
"$ref": "#/definitions/ErrorReason"
},
"examples": {
"ReferenceId already in use": "{\r\n \"code\": \"RESOURCE_ALREADY_EXIST\",\r\n \"message\": \"Duplicated reference id. Creation of resource failed.\"\r\n}",
"application/json": "{\r\n \"code\": \"PAYEE_NOT_FOUND\",\r\n \"message\": \"string\"\r\n}"
}
},
"500": {
"description": "Internal Error.",
"schema": {
"$ref": "#/definitions/ErrorReason"
},
"examples": {
"Incorrect currency for target environment": "{\r\n \"code\": \"INVALID_CURRENCY\",\r\n \"message\": \"Currency not supported.\"\r\n}",
"application/json": "{\r\n \"code\": \"PAYEE_NOT_FOUND\",\r\n \"message\": \"string\"\r\n}"
}
}
}
}
},
"/v1_0/transfer/{referenceId}": {
"get": {
"description": "This operation is used to get the status of a transfer. X-Reference-Id that was passed in the post is used as reference to the request.",
"operationId": "transfer-referenceId-GET",
"summary": "/transfer/{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,
"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.",
"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,
"type": "string"
}
],
"produces": [
"Successful transfer",
"Payer limit breached",
"API user insufficient balance",
"application/json",
"Transfer not found",
"Unspecified internal error"
],
"responses": {
"200": {
"description": "OK. Note that a failed transfer will be returned with this status too. The 'status' of the TransferResult can be used to determine the outcome of the request. The 'reason' field can be used to retrieve a cause in case of failure.",
"schema": {
"$ref": "#/definitions/TransferResult"
},
"examples": {
"Successful transfer": "{\r\n \"amount\": 100,\r\n \"currency\": \"UGX\",\r\n \"financialTransactionId\": 363440463,\r\n \"externalId\": 83453,\r\n \"payee\": {\r\n \"partyIdType\": \"MSISDN\",\r\n \"partyId\": 4609274685\r\n },\r\n \"status\": \"SUCCESSFUL\"\r\n}",
"Payer limit breached": "{\r\n \"amount\": 100,\r\n \"currency\": \"UGX\",\r\n \"externalId\": 83453,\r\n \"payee\": {\r\n \"partyIdType\": \"MSISDN\",\r\n \"partyId\": 4609274685\r\n },\r\n \"status\": \"FAILED\",\r\n \"reason\": {\r\n \"code\": \"PAYER_LIMIT_REACHED\",\r\n \"message\": \"The payer's limit has been breached.\"\r\n }\r\n}",
"API user insufficient balance": "{\r\n \"amount\": 100,\r\n \"currency\": \"UGX\",\r\n \"externalId\": 83453,\r\n \"payee\": {\r\n \"partyIdType\": \"MSISDN\",\r\n \"partyId\": 4609274685\r\n },\r\n \"status\": \"FAILED\",\r\n \"reason\": {\r\n \"code\": \"NOT_ENOUGH_FUNDS\",\r\n \"message\": \"The payer does not have enough funds.\"\r\n }\r\n}",
"application/json": "{\r\n \"amount\": \"string\",\r\n \"currency\": \"string\",\r\n \"financialTransactionId\": \"string\",\r\n \"externalId\": \"string\",\r\n \"payee\": {\r\n \"partyIdType\": \"MSISDN\",\r\n \"partyId\": \"string\"\r\n },\r\n \"payerMessage\": \"string\",\r\n \"payeeNote\": \"string\",\r\n \"status\": \"PENDING\",\r\n \"reason\": {\r\n \"code\": \"PAYEE_NOT_FOUND\",\r\n \"message\": \"string\"\r\n }\r\n}"
}
},
"400": {
"description": "Bad request, e.g. an incorrectly formatted reference id was provided."
},
"404": {
"description": "Resource not found.",
"schema": {
"$ref": "#/definitions/ErrorReason"
},
"examples": {
"Transfer not found": "{\r\n \"code\": \"RESOURCE_NOT_FOUND\",\r\n \"message\": \"Requested resource was not found.\"\r\n}",
"application/json": "{\r\n \"code\": \"PAYEE_NOT_FOUND\",\r\n \"message\": \"string\"\r\n}"
}
},
"500": {
"description": "Internal Error. Note that if the retreieved transfer has failed, it will not cause this status to be returned. This status is only returned if the GET request itself fails.",
"schema": {
"$ref": "#/definitions/ErrorReason"
},
"examples": {
"Unspecified internal error": "{\r\n \"code\": \"INTERNAL_PROCESSING_ERROR\",\r\n \"message\": \"An internal error occurred while processing.\"\r\n}",
"application/json": "{\r\n \"code\": \"PAYEE_NOT_FOUND\",\r\n \"message\": \"string\"\r\n}"
}
}
}
}
}
},
"definitions": {
"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",
"description": "The available balance of the account",
"properties": {
"availableBalance": {
"type": "string",
"description": "The available balance of the account"
},
"currency": {
"type": "string",
"description": "ISO4217 Currency"
}
}
},
"Party": {
"type": "object",
"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",
"properties": {
"partyIdType": {
"type": "string",
"enum": [
"MSISDN",
"EMAIL",
"PARTY_CODE"
]
},
"partyId": {
"type": "string"
}
}
},
"PreApproval": {
"type": "object",
"properties": {
"payer": {
"$ref": "#/definitions/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": "#/definitions/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": {
"type": "string",
"enum": [
"PENDING",
"SUCCESSFUL",
"FAILED"
]
},
"reason": {
"$ref": "#/definitions/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": "#/definitions/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": "#/definitions/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": {
"type": "string",
"enum": [
"PENDING",
"SUCCESSFUL",
"FAILED"
]
},
"reason": {
"$ref": "#/definitions/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": "#/definitions/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."
}
},
"example": "{\r\n \"amount\": \"string\",\r\n \"currency\": \"string\",\r\n \"externalId\": \"string\",\r\n \"payee\": {\r\n \"partyIdType\": \"MSISDN\",\r\n \"partyId\": \"string\"\r\n },\r\n \"payerMessage\": \"string\",\r\n \"payeeNote\": \"string\"\r\n}"
},
"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": "#/definitions/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": {
"type": "string",
"enum": [
"PENDING",
"SUCCESSFUL",
"FAILED"
]
},
"reason": {
"$ref": "#/definitions/ErrorReason"
}
}
},
"ErrorReason": {
"type": "object",
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string"
}
}
},
"BooleanResult": {
"type": "object",
"properties": {
"result": {
"type": "boolean"
}
}
}
},
"tags": []
}