openapi: 3.0.1
info:
title: Remittance
description: Partner Gateway API document
version: '1.0'
servers:
- url: https://proxy.momoapi.mtn.co.rw/remittance
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.
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].'
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 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/transfer:
post:
summary: /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
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 e.g. 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/Transfer'
example:
amount: string
currency: string
externalId: string
payee:
partyIdType: MSISDN
partyId: string
payerMessage: string
payeeNote: string
responses:
'202':
description: Accepted
content:
application/json: { }
ReferenceId already in use: { }
Incorrect currency for target environment: { }
'400':
description: 'Bad request, e.g. invalid data was sent in the request.'
content:
application/json: { }
ReferenceId already in use: { }
Incorrect currency for target environment: { }
'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
Incorrect currency for target environment:
schema:
$ref: '#/components/schemas/ErrorReason'
'500':
description: Internal Error.
content:
Incorrect currency for target environment:
schema:
$ref: '#/components/schemas/ErrorReason'
example:
code: INVALID_CURRENCY
message: Currency not supported.
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/transfer/{referenceId}':
get:
summary: '/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
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 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.
content:
Successful transfer:
schema:
$ref: '#/components/schemas/TransferResult'
example:
amount: 100
currency: UGX
financialTransactionId: 363440463
externalId: 83453
payee:
partyIdType: MSISDN
partyId: 4609274685
status: SUCCESSFUL
Payer limit breached:
schema:
$ref: '#/components/schemas/TransferResult'
example:
amount: 100
currency: UGX
externalId: 83453
payee:
partyIdType: MSISDN
partyId: 4609274685
status: FAILED
reason:
code: PAYER_LIMIT_REACHED
message: The payer's limit has been breached.
API user insufficient balance:
schema:
$ref: '#/components/schemas/TransferResult'
example:
amount: 100
currency: UGX
externalId: 83453
payee:
partyIdType: MSISDN
partyId: 4609274685
status: FAILED
reason:
code: NOT_ENOUGH_FUNDS
message: The payer does not have enough funds.
application/json:
schema:
$ref: '#/components/schemas/TransferResult'
example:
amount: string
currency: string
financialTransactionId: string
externalId: string
payee:
partyIdType: MSISDN
partyId: string
payerMessage: string
payeeNote: string
status: PENDING
reason:
code: PAYEE_NOT_FOUND
message: string
Transfer not found:
schema:
$ref: '#/components/schemas/TransferResult'
Unspecified internal error:
schema:
$ref: '#/components/schemas/TransferResult'
'400':
description: 'Bad request, e.g. an incorrectly formatted reference id was provided.'
content:
Successful transfer: { }
Payer limit breached: { }
API user insufficient balance: { }
application/json: { }
Transfer not found: { }
Unspecified internal error: { }
'404':
description: Resource not found.
content:
Transfer not found:
schema:
$ref: '#/components/schemas/ErrorReason'
example:
code: RESOURCE_NOT_FOUND
message: Requested resource was not found.
Successful transfer:
schema:
$ref: '#/components/schemas/ErrorReason'
Payer limit breached:
schema:
$ref: '#/components/schemas/ErrorReason'
API user insufficient balance:
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 retreieved transfer 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 transfer:
schema:
$ref: '#/components/schemas/ErrorReason'
Payer limit breached:
schema:
$ref: '#/components/schemas/ErrorReason'
API user insufficient balance:
schema:
$ref: '#/components/schemas/ErrorReason'
application/json:
schema:
$ref: '#/components/schemas/ErrorReason'
example:
code: PAYEE_NOT_FOUND
message: string
Transfer 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: [ ]