1.
Create a Direct Debit Mandate for a Payer Customer
(Customer or SP Operator)
Before using the direct debit service, the payer or payee must create a direct debit mandate
to reach an entrusted fee deduction agreement. A customer can create a direct debit
mandate or entrust an SP operator to create a direct debit mandate and use the direct debit
service as the payer. This interface is invoked by a third party of the Mobile Money system
to create a direct debit mandate for a payer customer.
Request Parameter Specification
Common field specification
Command CreateDirectDebitMandateByCustomer
ID
Initiator
Customer MSISDN/PIN
User Name of an SP Operator/Password
PrimaryPar Not required
ty
ReceiverPa Customer MSISDN
rty
Body specification
Element Request/Body/CreateDirectDebitMandateByPayerRequest
Element CreateDirectDebitMandateByPayerRequest
Type
Fields in CreateDirectDebitMandateByPayerRequest type
Mandatory
Parameter Data Type or Optional Description Example
Payee IdentifierTy Mandatory Indicates the identifier type IdentifierTyp
peValue information of payee in the e
direct debit mandate.
DirectDebit DirectDebit Mandatory Indicates the basic PayerRefere
MandateInfo MandateInfo information about the direct nceNumber
debit mandate.
Result Parameter Specification
Specific parameters in Result/ResultParameters
No specific parameter for this result message.
Instance
Request messages
<soapenv:Envelope xmlns:soapenv="[Link]
xmlns:api="[Link]
xmlns:req="[Link]
xmlns:com="[Link]
<soapenv:Header/>
<soapenv:Body>
<api:Request>
<req:Header>
<req:Version>1.0</req:Version>
<req:CommandID>CreateDirectDebitMandateByCustomer</req:CommandID>
<req:OriginatorConversationID>S_X2013012921001</req:OriginatorConversationID
>
<req:ConversationID>AG_20130129T102103</req:ConversationID>
<req:Caller>
<req:CallerType>2</req:CallerType>
<req:ThirdPartyID>POS_Broker</req:ThirdPartyID>
<req:Password>B1YNY8GylVo=</req:Password>
<req:ResultURL>[Link]
</req:Caller>
<req:KeyOwner>1</req:KeyOwner>
<req:Timestamp>20130402152345</req:Timestamp>
</req:Header>
<req:Body>
<req:Identity>
<req:Initiator>
<req:IdentifierType>14</req:IdentifierType>
<req:Identifier>AAA</req:Identifier>
<req:SecurityCredential>kMhIAmNE4h8=</req:SecurityCredential>
</req:Initiator>
<req:ReceiverParty>
<req:IdentifierType>1</req:IdentifierType>
<req:Identifier>86812530001</req:Identifier>
</req:ReceiverParty>
</req:Identity>
<req:CreateDirectDebitMandateByPayerRequest>
<req:Payee>
<com:IdentifierType>4</com:IdentifierType>
<com:IdentifierValue>1008</com:IdentifierValue>
</req:Payee>
<req:DirectDebitMandateInfo>
<com:PayerReferenceNumber>1111</com:PayerReferenceNumber>
<com:AgreedTC>1</com:AgreedTC>
<com:PayeeAccountName>PayeeAccount</com:PayeeAccountName>
<com:PayerAccountName>PayerAccount</com:PayerAccountName>
<com:FirstPaymentDate>20160324</com:FirstPaymentDate>
<com:Frequency>06</com:Frequency>
<com:StartRangeOfDays>1</com:StartRangeOfDays>
<com:EndRangeOfDays>22</com:EndRangeOfDays>
<com:ExpiryDate>20161126</com:ExpiryDate>
</req:DirectDebitMandateInfo>
</req:CreateDirectDebitMandateByPayerRequest>
</req:Body>
</api:Request>
</soapenv:Body>
</soapenv:Envelope>
Response messages
<soapenv:Envelope xmlns:soapenv="[Link]
<soapenv:Body>
<api:Response
xmlns:api="[Link]
xmlns:res="[Link]
<res:Header>
<res:Version>1.0</res:Version>
<res:OriginatorConversationID>S_X2013012921001</res:OriginatorConversationID
>
<res:ConversationID>AG_20130129_00006a0ed354a438dd05</res:ConversationID>
</res:Header>
<res:Body>
<res:ResponseCode>0</res:ResponseCode>
<res:ResponseDesc>Accept the service request
successfully.</res:ResponseDesc>
<res:ServiceStatus>0</res:ServiceStatus>
</res:Body>
</api:Response>
</soapenv:Body>
</soapenv:Envelope>
Result messages
<soapenv:Envelope xmlns:soapenv="[Link]
<soapenv:Body>
<api:Result xmlns:api="[Link]
xmlns:res="[Link]
xmlns:com="[Link]
<res:Header>
<res:Version>1.0</res:Version>
<res:OriginatorConversationID>S_X2013012921001</res:OriginatorConversationID
>
<res:ConversationID>AG_20130129T102103</res:ConversationID>
</res:Header>
<res:Body>
<res:ResultType>0</res:ResultType>
<res:ResultCode>0</res:ResultCode>
<res:ResultDesc>Process service request
successfully.</res:ResultDesc>
</res:Body>
</api:Result>
</soapenv:Body>
</soapenv:Envelope>
2. Activate a Customer Direct Debit Mandate (Customer
or SP Operator)
A direct debit mandate created for a payee organization is in Pending Active state. The
direct debit mandate takes effect only after being activated by the payer. This interface is
invoked by a third party of the Mobile Money system to activate a direct debit mandate for
a payer customer.
Request Parameter Specification
Common field specification
Command ActivateCustomerDirectDebitMandate
ID
Initiator
Customer MSISDN/PIN
User Name of an SP Operator/Password
PrimaryPar Not required
ty
ReceiverPa Customer MSISDN
rty
Body specification
Element Request/Body/ActivateDirectDebitMandateRequest
Element ActivateDirectDebitMandateRequest
Type
Fields in ActivateDirectDebitMandateRequest type
Mandatory
Parameter Data Type or Optional Description Example
MandateID xs:string Mandatory Indicates the unique 10101
mandate ID, which is
automatically generated by
the Mobile Money system.
NOTE
The max length is 18 bytes.
AgreedTC xs:string Mandatory Indicates whether to agree 1
with the Agreed Terms and
Conditions. The values are
as follows:
0: No
1: Yes
Common field specification
NOTE
The max length is 1 bytes.
PayerAccou xs:string Optional Indicates the account name PayerAccou
ntName of the payer. nt
NOTE
The max length is 64 bytes.
Result Parameter Specification
Specific parameters in Result/ResultParameters
No specific parameter for this result message.
Instance
Request messages
<soapenv:Envelope xmlns:soapenv="[Link]
xmlns:api="[Link]
xmlns:req="[Link]
xmlns:com="[Link]
<soapenv:Header/>
<soapenv:Body>
<api:Request>
<req:Header>
<req:Version>1.0</req:Version>
<req:CommandID>ActivateCustomerDirectDebitMandate</req:CommandID>
<req:OriginatorConversationID>S_X2013012921001</req:OriginatorConversationID
>
<req:ConversationID>AG_20130129T102103</req:ConversationID>
<req:Caller>
<req:CallerType>2</req:CallerType>
<req:ThirdPartyID>POS_Broker</req:ThirdPartyID>
<req:Password>B1YNY8GylVo=</req:Password>
<req:ResultURL>[Link]
</req:Caller>
<req:KeyOwner>1</req:KeyOwner>
<req:Timestamp>20130402152345</req:Timestamp>
</req:Header>
<req:Body>
<req:Identity>
<req:Initiator>
<req:IdentifierType>14</req:IdentifierType>
<req:Identifier>AAA</req:Identifier>
<req:SecurityCredential>kMhIAmNE4h8=</req:SecurityCredential>
</req:Initiator>
<req:ReceiverParty>
<req:IdentifierType>1</req:IdentifierType>
<req:Identifier>86812530001</req:Identifier>
</req:ReceiverParty>
</req:Identity>
<req:ActivateDirectDebitMandateRequest>
<req:MandateID>10101</req:MandateID>
<req:AgreedTC>1</req:AgreedTC>
<req:PayerAccountName>PayerAccount</req:PayerAccountName>
</req:ActivateDirectDebitMandateRequest>
</req:Body>
</api:Request>
</soapenv:Body>
</soapenv:Envelope>
Response messages
<soapenv:Envelope xmlns:soapenv="[Link]
<soapenv:Body>
<api:Response
xmlns:api="[Link]
xmlns:res="[Link]
<res:Header>
<res:Version>1.0</res:Version>
<res:OriginatorConversationID>S_X2013012921001</res:OriginatorConversationID
>
<res:ConversationID>AG_20130129_00006a0ed354a438dd05</res:ConversationID>
</res:Header>
<res:Body>
<res:ResponseCode>0</res:ResponseCode>
<res:ResponseDesc>Accept the service request
successfully.</res:ResponseDesc>
<res:ServiceStatus>0</res:ServiceStatus>
</res:Body>
</api:Response>
</soapenv:Body>
</soapenv:Envelope>
Result messages
<soapenv:Envelope xmlns:soapenv="[Link]
<soapenv:Body>
<api:Result xmlns:api="[Link]
xmlns:res="[Link]
xmlns:com="[Link]
<res:Header>
<res:Version>1.0</res:Version>
<res:OriginatorConversationID>S_X2013012921001</res:OriginatorConversationID
>
<res:ConversationID>AG_20130129T102103</res:ConversationID>
</res:Header>
<res:Body>
<res:ResultType>0</res:ResultType>
<res:ResultCode>0</res:ResultCode>
<res:ResultDesc>Process service request
successfully.</res:ResultDesc>
</res:Body>
</api:Result>
</soapenv:Body>
</soapenv:Envelope>
3. Initiate a Direct Debit Transaction (Organization
Operator or SP Operator)
An organization can deduct a fee amount from an identity by initiating the direct debit
service. When the service succeeds, e-money is transferred from the payer's Mobile
Money system account to the payee organization's Mobile Money system account. This
interface is invoked by a third party of the Mobile Money system to initiate a direct debit
transaction.
Request Parameter Specification
Common field specification
Command Follow InitTrans_{ServiceCode} format
ID
Initiator
Operator ID of an Organization Operator/PIN/ShortCode
User Name of an Organization Operator/Password/ShortCode
User Name of an SP Operator/Password
PrimaryPar Not required
ty
ReceiverPa Payer ReferenceNumber
rty
Requester Not required
Specific parameters in Request/Transaction/Parameters
Mandatory
Parameter Data Type or Optional Description Example
MandateID ParameterTy Optional Indicates the unique 10001
pe mandate ID.
NOTE
The max length is 18 bytes.
Amount ParameterTy Mandatory Indicates the amount 100.00
pe directly debited from a
payer's e-money account.
Common field specification
Currency ParameterTy Optional Indicates the currency type. USD
pe It is specified by using the
Char 3 Code defined in the
ISO 4217 standard.
Result Parameter Specification
Specific parameters in
Result/Body/TransactionResult/ResultParameters
No specific parameter for this result message.
Instance
Request messages
<soapenv:Envelope xmlns:soapenv="[Link]
xmlns:api="[Link]
xmlns:req="[Link]
xmlns:com="[Link]
<soapenv:Header/>
<soapenv:Body>
<api:Request>
<req:Header>
<req:Version>1.0</req:Version>
<req:CommandID>InitTrans_Initiate Direct Debit
Transaction</req:CommandID>
<req:OriginatorConversationID>S_X2013012921001</req:OriginatorConversationID
>
<req:Caller>
<req:CallerType>2</req:CallerType>
<req:ThirdPartyID>POS_Broker</req:ThirdPartyID>
<req:Password>B1YNY8GylVo=</req:Password>
<req:ResultURL>[Link]
</req:Caller>
<req:KeyOwner>1</req:KeyOwner>
<req:Timestamp>20130402152345</req:Timestamp>
</req:Header>
<req:Body>
<req:Identity>
<req:Initiator>
<req:IdentifierType>11</req:IdentifierType>
<req:Identifier>aaa</req:Identifier>
<req:SecurityCredential>iUoiP9iGVwE=</req:SecurityCredential>
<req:ShortCode>1008</req:ShortCode>
</req:Initiator>
<req:ReceiverParty>
<req:IdentifierType>53</req:IdentifierType>
<req:Identifier>1111</req:Identifier>
</req:ReceiverParty>
</req:Identity>
<req:TransactionRequest>
<req:Parameters>
<req:Parameter>
<com:Key>MandateID</com:Key>
<com:Value>10001</com:Value>
</req:Parameter>
<req:Parameter>
<com:Key>Amount</com:Key>
<com:Value>100.00</com:Value>
</req:Parameter>
<req:Parameter>
<com:Key>Currency</com:Key>
<com:Value>USD</com:Value>
</req:Parameter>
</req:Parameters>
</req:TransactionRequest>
<req:Remark>1212</req:Remark>
</req:Body>
</api:Request>
</soapenv:Body>
</soapenv:Envelope>
Response messages
<soapenv:Envelope xmlns:soapenv="[Link]
<soapenv:Body>
<api:Response
xmlns:api="[Link]
xmlns:res="[Link]
<res:Header>
<res:Version>1.0</res:Version>
<res:OriginatorConversationID>S_X2013012921001</res:OriginatorConversationID
>
<res:ConversationID>AG_20130129_00006a0ed354a438dd05</res:ConversationID>
</res:Header>
<res:Body>
<res:ResponseCode>0</res:ResponseCode>
<res:ResponseDesc>Accept the service request
successfully.</res:ResponseDesc>
<res:ServiceStatus>0</res:ServiceStatus>
</res:Body>
</api:Response>
</soapenv:Body>
</soapenv:Envelope>
Result messages
<soapenv:Envelope xmlns:soapenv="[Link]
<soapenv:Body>
<api:Result
xmlns:api="[Link]
xmlns:res="[Link]
<res:Header>
<res:Version>1.0</res:Version>
<res:OriginatorConversationID>S_X2013012921001</res:OriginatorConversationID
>
<res:ConversationID>AG_20130129_00006a0ed354a438dd05</res:ConversationID>
</res:Header>
<res:Body>
<res:ResultType>0</res:ResultType>
<res:ResultCode>0</res:ResultCode>
<res:ResultDesc>Process service request
successfully.</res:ResultDesc>
<res:TransactionResult>
<res:TransactionID>5HL20005L6</res:TransactionID>
</res:TransactionResult>
<res:ReferenceData/>
</res:Body>
</api:Result>
</soapenv:Body>
</soapenv:Envelope>
4. Cancel a Direct Debit Mandate for a Payer Customer
(Customer or SP Operator)
Customers can cancel direct debit mandates using their own devices based on the payer
customer requirements. Then the direct debit mandate is in Cancelled state. An SP operator
with the correct permission can cancel a direct debit mandate on behalf of a customer. This
interface is invoked by a third party of the Mobile Money system to cancel a direct debit
mandate for a payer customer.
Request Parameter Specification
Common field specification
Command CancelCustomerDirectDebitMandateByPayer
ID
Initiator
Customer MSISDN/PIN
User Name of an SP Operator/Password
PrimaryPar Not required
ty
ReceiverPa Customer MSISDN
rty
Body specification
Common field specification
Element Request/Body/CancelDirectDebitMandateByPayerRequest
Element CancelDirectDebitMandateByPayerRequest
Type
Fields in CancelDirectDebitMandateByPayerRequest type
Mandatory
Parameter Data Type or Optional Description Example
MandateID xs:string Mandatory Indicates the unique 10101
mandate ID.
NOTE
The max length is 18 bytes.
Result Parameter Specification
Specific parameters in Result/ResultParameters
No specific parameter for this result message.
Instance
Request messages
<soapenv:Envelope xmlns:soapenv="[Link]
xmlns:api="[Link]
xmlns:req="[Link]
xmlns:com="[Link]
<soapenv:Header/>
<soapenv:Body>
<api:Request>
<req:Header>
<req:Version>1.0</req:Version>
<req:CommandID>CancelCustomerDirectDebitMandateByPayer</req:CommandID>
<req:OriginatorConversationID>S_X20190625202317</req:OriginatorConversationI
D>
<req:Caller>
<req:CallerType>2</req:CallerType>
<req:ThirdPartyID>POS_Broker</req:ThirdPartyID>
<req:Password>guQOmb66A6HRGIwZHqCiFrI5IJB/o7Cj8DKPbSnILwZ3szmaZp1uIvn1pDAxCF
Q9laaQF7LcekovCI0CT7hiNA==</req:Password>
<req:ResultURL>[Link]
RL>
</req:Caller>
<req:KeyOwner>1</req:KeyOwner>
<req:Timestamp>20190625202317</req:Timestamp>
</req:Header>
<req:Body>
<req:Identity>
<req:Initiator>
<req:IdentifierType>14</req:IdentifierType>
<req:Identifier>0000</req:Identifier>
<req:SecurityCredential>yeZchuDV/vamwswucSwm4ziZZZm6ogcm40eFAIc7H69e76ZT/
CibWDWac6uE14cWzB7qiFHlW/4JL1EzBLMj7g==</req:SecurityCredential>
</req:Initiator>
<req:ReceiverParty>
<req:IdentifierType>1</req:IdentifierType>
<req:Identifier>8610000087004</req:Identifier>
</req:ReceiverParty>
</req:Identity>
<req:CancelDirectDebitMandateByPayerRequest>
<req:MandateID>12502</req:MandateID>
</req:CancelDirectDebitMandateByPayerRequest>
</req:Body>
</api:Request>
</soapenv:Body>
</soapenv:Envelope>
Response messages
<soapenv:Envelope xmlns:soapenv="[Link]
<soapenv:Body>
<api:Response
xmlns:api="[Link]
xmlns:res="[Link]
<res:Header>
<res:Version>1.0</res:Version>
<res:OriginatorConversationID>S_X20190625202317</res:OriginatorConversationI
D>
<res:ConversationID>AG_20190710_000049aed29659e2ca2c</res:ConversationID>
</res:Header>
<res:Body>
<res:ResponseCode>0</res:ResponseCode>
<res:ResponseDesc>Accept the service request
successfully.</res:ResponseDesc>
<res:ServiceStatus>0</res:ServiceStatus>
</res:Body>
</api:Response>
</soapenv:Body>
</soapenv:Envelope>
Result messages
<soapenv:Envelope xmlns:soapenv="[Link]
<soapenv:Body>
<api:Result
xmlns:api="[Link]
xmlns:res="[Link]
<res:Header>
<res:Version>1.0</res:Version>
<res:OriginatorConversationID>S_X20190625202317</res:OriginatorConversationI
D>
<res:ConversationID>AG_20190710_000049aed29659e2ca2c</res:ConversationID>
</res:Header>
<res:Body>
<res:ResultType>0</res:ResultType>
<res:ResultCode>0</res:ResultCode>
<res:ResultDesc>Process service request
successfully.</res:ResultDesc>
<res:ReferenceData/>
</res:Body>
</api:Result>
</soapenv:Body>
</soapenv:Envelope>