@aberba/hubtel 中文文档教程

Question

Hubtel API

这是用于 Node.js 的非官方 Hubtel API。

Installation

使用 Node.js v8.X 或最新版本，您可以使用以下方式安装：

npm install hubtel-mx

警告：Hubtel 的 API 有一些您需要注意的怪癖、规则和限制。 在使用此软件包之前，我建议您阅读与您计划使用的服务相关的 API 参考。 相信我，你会用自己的日子来拯救自己的……呃……嗯……沮丧。

从安全的角度来看，将所有帐户 API 密钥和其他凭据存储在环境变量中比将它们硬编码在源代码中要安全得多。

Mobile Money API

Config 类用于 API 配置。 用您自己的帐户信息替换下面提供的信息。 查看 Hubtel Merhcant API 文档了解更多信息。

const {
    MobileMoney,
    Config,
    getErrorMessageFromResponseCode
} = require("hubtel-mx");

// Use your own account credentials
const secret = {
    clientId: "XXXXXXXXX",
    clientSecret: "XXXXXXXXXXXXXXXX",
    merchantAccountNumber: "HMXXXXXXXXX"
};

const config = new Config({
    clientId: secret.clientId,
    clientSecret: secret.clientSecret,
    merchantAccountNumber: secret.merchantAccountNumber
});

const mobileMoney = new MobileMoney(config);

mobileMoney
    .receive({
        CustomerName: "Mary Doe",
        CustomerMsisdn: "05XXXXXXXX",
        CustomerEmail: "user@example.com",
        Channel: "mtn-gh",
        Amount: 7.55,
        PrimaryCallbackUrl: "https://example.com/payment_callback",
        Description: "A bowl of gari",
        ClientReference: "UniqueXXXXX21XX"
    })
    .then(responseJSON => {
        console.log(responseJSON);
        console.log(
            "Response message: ",
            getErrorMessageFromResponseCode(responseJSON.ResponseCode)
        );
    })
    .catch(err => console.log(err));

mobileMoney
    .send({
        RecipientName: "Adongo Samuel",
        RecipientMsisdn: "23327XXXXXXX",
        CustomerEmail: "user@example.com",
        Channel: "tigo-gh",
        Amount: 60.05,
        PrimaryCallbackUrl: "https://example.com/payment_callback",
        SecondaryCallbackUrl: "",
        Description: "Monthly rent payment",
        ClientReference: "UniqueXXXXX21XX"
    })
    .then(responseJSON => console.log(responseJSON))
    .catch(err => console.log(err));

// Getting errors messages
console.log("Code 0000 message:", getErrorMessageFromResponseCode("0000"));

// Cool guys use fat arrows, async and await from ES6 ;)
const payUsualBills = async ClientReference => {
    const paymentData = {
        RecipientName: "Tax tax tax!!",
        RecipientMsisdn: "23327XXXXXXX",
        CustomerEmail: "user@example.com",
        Channel: "tigo-gh",
        Amount: 100000.01,
        PrimaryCallbackUrl: "https://example.com/payment_callback",
        SecondaryCallbackUrl: "",
        Description: "Monthly tax payment"
    };

    return await mobileMoney.send(Object.assign(paymentData, ClientReference)); // object destructuring in future
};

// may throw, wrap in try catch block to handle errors
console.log(payUsualBills("UniqueXXXXX21XX"));

Note (Mobile Money API)

String getErrorMessageFromResponseCode(String code) 函数使用作为参数传递的 API 响应代码返回错误消息。 其中一些消息是文档中可用内容的修改版本……因此（根据我的判断）在向客户显示时比 API 响应提供的消息更清晰（responseJSON.Data.Description). 使用 responseJSON.Data.Description 与 Hubtel 相提并论。

SMS Messaging API

Config 类用于 API 配置。 用您自己的帐户信息替换下面提供的信息。 查看 Hubtel SMS API 文档了解更多信息。

const { SMSMessage, Config } = require("hubtel-mx");

const secret = {
    clientId: "XXXXXXXXX",
    clientSecret: "XXXXXXXXXXXXXXXX",
    merchantAccountNumber: "HMXXXXXXXXX"
};

const config = new Config({
    clientId: secret.clientId,
    clientSecret: secret.clientSecret
});

const message = new SMSMessage(config);

message
    .sendOne({
        From: "smsgh",
        To: "+233248183797",
        Content: "hello, world!",
        RegisteredDelivery: "true",
        Time: "2014-01-01 10:00:00"
    })
    .then(responseJSON => {
        console.log(responseJSON);
    })
    .catch(err => console.log(err));

// Using ES6 async and await
(async () => {
    try {
        // using GET request
        const response = await message.get({
            From: "smsgh",
            To: "+233248183797",
            Content: "hello, world!",
            RegisteredDelivery: "true",
            Time: "2014-01-01 10:00:00"
        });

        console.log(response);
    } catch (error) {
        console.error(error);
    }
})();

Note (SMS Messaging API)

其他功能可用于发送 SMS 消息。 有关它们接受的其他参数，请参阅 SMS 消息传递文档。 列表包括：

• sendOne(messageInfomation) {}: Sends a single message
• schedule(messageInfomation) {}: Schedule message to be sent later at time provided as Time argument.

API 配置中使用的 URL 可以通过在实例化期间设置 Config() 类的 apiBaseURL 参数来覆盖。

const config = new Config({
      apiBaseURL: "https://api.hubtel.com/v1/messages/{MESSAGE_ID}",
      clientId: secret.clientId,
      clientSecret: secret.clientSecret
});

• reschedule(messageInfomation) {}: Reschedule messages to be sent later at time provided as Time argument. Configuration URL must be in the format https://api.hubtel.com/v1/messages/{messageId} .
• cancelSchedule() {}: Cancels a scheduled message that has not already been sent using the message ID provided as argument to the configuration Configuration URL must be in the format https://api.smsgh.com/v3/messages/{messageId} .
• get(messageInfomation) {}: Send message using GET request. Parameters are transformed to encoded URL query parameters.
• query() {}: Query messages that have been sent or received on your account.

Todo

• Create schema for send and receive payment data with in-built validation
• Improve code test coverage
  • send() and receive()
  • API call responses
• Improve API documentation

Hacking

欢迎您提交代码和文档的拉取请求或对 API 提出建议。