@chipdeals/payments
v1.1.0
Published
Chipdeals Payment
Downloads
23
Maintainers
Readme
Mobile Money REST API, and Nodejs Library documentation
Chipdeals-payments is a payment API that allows you to build a quick, simple and excellent payment experience with Mobile money or banc card in your web and native app.This the official Nodejs Library.
You can request payment and send money to any mobile money account
Requirements
Node 8, 10 or higher
Installation
npm install @chipdeals/payments --save
# or
yarn add @chipdeals/payments
Quick Start
Initialize Chipdeals Momo API with your API Key (Get apikey here) and start
const chipdeals = require('@chipdeals/payments');
chipdeals.setApiKey('test_FOdigzgSopV8GZggZa89');
//Collect 500 XOF from the +22951010200 Mobile Money wallet.
chipdeals
.collect()
.amount(500) //Amount of the transaction
.currency('XOF') // Any valid currency
.from('22951010200') // Sender phone number with country code préfix
.create();
//Send 2000 XOF to the +22951010200 Mobile Money wallet.
chipdeals
.deposit()
.amount(2000) //Amount of the transaction
.currency('XOF') // Any valid currency
.to('22951010200') // Recipient phone number with country code préfix
.create();
Quick check possible responses with sandbox tests
Usage
The package needs to be configured with your account's API key, which is available in the when you get access to Chipdeals Sandbox.
Collect Money
Simple collection
For example to request 2000 XOF from the +22951010200 Mobile Money wallet, the following code can be used
const chipdeals = require('@chipdeals/payments');
chipdeals.setApiKey('test_FOdigzgSopV8GZggZa89');
chipdeals
.collect()
.amount(2000) //Amount of the transaction
.currency('XOF') // Any valid currency
.from('22951010200') // Sender phone number with country code préfix
.firstName('Jean') // First name of the sender
.lastName('Luc') // Last name of the sender
.create(transacrionReference => console.log(transacrionReference));
Collect with a webhook to get response as soon as the payment is processed.
chipdeals
.collect()
.amount(2000) //Amount of the transaction
.currency('XOF') // Any valid currency
.from('22951010200') // Sender phone number with country code préfix
.setFee(10, false) // Fee you want to add in percent. The boolean specify if you want the user to pay all fees
.firstName('Jean') // First name of the sender
.lastName('Luc') // Last name of the sender
.webhook('https://mydomain/payment-status')
.create(transacrionReference => console.log(transacrionReference));
Make Collection using Callbacks.
chipdeals
.collect()
.amount(2000) //Amount of the transaction
.currency('XOF') // Any valid currency
.from('22951010200') // Sender phone number with country code préfix
.firstName('Jean') // First name of the sender
.lastName('Luc') // Last name of the sender
.create(transacrionReference => console.log(transacrionReference))
.onStatusChanged(paymentData => console.log(paymentData))
.onSuccess(paymentData => console.log(paymentData))
.onError(paymentData => console.error(paymentData));
See what you receive as callback parametters
Disburse Money
Simple Disbursement
You can also send 2000 XOF to the +22951010200 Mobile Money wallet, with the following code
const chipdeals = require('@chipdeals/payments');
chipdeals.setApiKey('test_FOdigzgSopV8GZggZa89');
chipdeals
.deposit()
.amount(2000) //Amount of the transaction
.currency('XOF') // Any valid currency
.to('22951010200') // Recipient phone number with country code préfix
.create(transacrionReference => console.log(transacrionReference));
Disburse with a webhook to get response as soon as the deposit is processed.
chipdeals
.deposit()
.amount(2000) //Amount of the transaction
.currency('XOF') // Any valid currency
.to('22951010200') // Recipient phone number with country code préfix
.webhook('https://mydomain/deposit-status')
.create(transacrionReference => console.log(transacrionReference));
Make Disbursement using Callbacks.
chipdeals
.deposit()
.amount(2000) //Amount of the transaction
.currency('XOF') // Any valid currency
.to('22951010200') // Recipient phone number with country code préfix
.create(transacrionReference => console.log(transacrionReference))
.onSuccess(depositData => console.log(depositData))
.onError(depositData => console.error(depositData));
See what you receive as callback parametters
Get transaction status
Get status of a transaction of reference dd1e2d17-5c21-4964-b58d-198fd2aac150
const chipdeals = require('@chipdeals/payments');
chipdeals.setApiKey('test_FOdigzgSopV8GZggZa89');
const reference = "dd1e2d17-5c21-4964-b58d-198fd2aac150";
chipdeals
.status(reference)
.then((transactionData)=>console.log(transactionData))
{
"type": "collection", //the type of the transaction
"reference": "dd1e2d17-5c21-4964-b58d-198fd2aac150",
"status": "success",
"statusMessageCode": 200,
"statusMessage": "transaction successfully processed",
"senderPhoneNumber": "22951010200", //Phonenumeber you speciy in your collection request
"senderFirstName": "Euler", //User firstname you specified in your collect request
"senderLastName": "Dougbe", //User lastname you specified in your collect request
"currency": "XOF", //Currency of the transaction.
"amount": 2000, //Amount of the transaction
"senderOperator": "MTN", // Mobile Money wallet operator
"startTimestampInSecond": 1638087167, // Timestamp in second of whe you init the transaction
"endTimestampInSecond": 1638087167 // Timestamp in second of when the transaction is finished
}
{
"type": "deposit", //the type of the transaction
"reference": "dd1e2d17-5c21-4964-b58d-198fd2aac150",
"status": "success",
"statusMessageCode": 200,
"statusMessage": "success",
"recipientPhoneNumber": "22951010200", //Phone number you specify in your deposit request
"currency": "XOF", //Currency of the transaction.
"amount": 2000, //Amount of the transaction
"senderOperator": "MTN", // Mobile Money wallet operator
"startTimestampInSecond": 1638087167, // Timestamp in second of whe you init the transaction
"endTimestampInSecond": 1638087167 //Timestamp in second of when the transaction is finished
}
Get Your balance
Get your Chipdeals account's balance
const chipdeals = require('@chipdeals/payments');
chipdeals.setApiKey('test_FOdigzgSopV8GZggZa89');
chipdeals
.balance()
.then((balance)=>console.log(balance))
Balance sample:
[
{
"amount": 2000,
"currency": "XOF"
},
{
"amount": 1045,
"currency": "XAF"
},
]
Webhook
Webhooks are an important part of your payment integration. They allow Chipdeals notify you about events that happen on your account, such as a successful payment or a failed transaction.
A webhook URL is an endpoint on your server where you can receive notifications about such events. When an event occurs, we'll make a POST request to that endpoint, with a JSON body containing the details about the event, including the type of event and the data associated with it.
Structure of a webhook payload
All webhook payloads follow the same basic structure:
- an
event
field describing the type of event - a
data
object. The contents of this object will vary depending on the event, but typically it will contain details of the event, including:- a
reference
containing the ID of the transaction - a
status
describing the status of the transaction. possible values aresuccess
,pending
orerror
- a
statusMessageCode
, containing a specific code that identify an exact state of the transaction. See allstatusMessageCode
- a
statusMessage
, cantaining an human undertandable descrption of the exact state of the transaction - transaction details
- a
Here are some sample webhook payloads for transfers and payments
Implementing a webhook
Creating a webhook endpoint on your server is the same as writing any other API endpoint, but there are a few important details to note:
Verifying webhook signatures When enabling webhooks, you have the option to set a secret hash. Since webhook URLs are publicly accessible, the secret hash allows you to verify that incoming requests are from Chipdeals. You can specify any value as your secret hash, but we recommend something random. We also recommend to store it as an environment variable on your server.
If you specify a secret hash, we'll include it in our request to your webhook URL, in a header called verif-hash
. In the webhook endpoint, check if the verif-hash
header is present and that it matches the secret hash you set. If the header is missing, or the value doesn't match, you can discard the request, as it isn't from Chipdeals.
Responding to webhook requests
To acknowledge receipt of a webhook, your endpoint must return a 200
HTTP status code. Any other response codes, including 3xx
codes, will be treated as a failure. We don't care about the response body or headers.
Be sure to enable webhook retries on your dashboard. If we don't get a 200 status code (for example, if your server is unreachable), we'll retry the webhook call every 90 minutes for the next 36 hours.
Webhook payload sample
Collectiton state changed webhook payload sample
{
"event": "collection.stateChanged",
"data": {
"reference": "dd1e2d17-5c21-4964-b58d-198fd2aac150",
"status": "success",
"statusMessageCode": 200,
"statusMessage": "transaction successfully processed",
"senderPhoneNumber": "22951010200", //Phonenumeber you speciy in your collection request
"senderFirstName": "Euler", //User firstname you specified in your collect request
"senderLastName": "Dougbe", //User lastname you specified in your collect request
"currency": "XOF", //Currency of the transaction.
"amount": 2000, //Amount of the transaction
"senderOperator": "MTN", // Mobile Money wallet operator
"startTimestampInSecond": 1638087167, // Timestamp in second of whe you init the transaction
"endTimestampInSecond": 1638087167 // Timestamp in second of when the transaction is finished
}
}
Disbursement state changed webhook payload sample
{
"event": "deposit.stateChanged",
"data": {
"reference": "dd1e2d17-5c21-4964-b58d-198fd2aac150",
"status": "success",
"statusMessageCode": 200,
"statusMessage": "success",
"recipientPhoneNumber": "22951010200", //Phone number you specify in your deposit request
"currency": "XOF", //Currency of the transaction.
"amount": 2000, //Amount of the transaction
"senderOperator": "MTN", // Mobile Money wallet operator
"startTimestampInSecond": 1638087167, // Timestamp in second of whe you init the transaction
"endTimestampInSecond": 1638087167 //Timestamp in second of when the transaction is finished
}
}
Callback
Call back allow to be notified in your code as soon as events happen about your transaction, such as a successful payment or a failed transaction.
When an event occurs, we'll call concerned callback function and will pass a single parametter containing the details about the event, the state of the transaction and the data associated with it.
Structure of callback data
All webhook payloads (except virtual card debits) follow the same basic structure:
- an
event
field describing the type of event - a
data
object. The contents of this object will vary depending on the event, but typically it will contain details of the event, including:- a
reference
containing the ID of the transaction - a
statusMessageCode
, containing a specific code that identify an exact state of the transaction. See allstatusMessageCode
- a
statusMessage
, cantaining an human undertandable descrption of the exact state of the transaction - transaction details
- a
Callback data sample
Collection callback data sample
{
"reference": "dd1e2d17-5c21-4964-b58d-198fd2aac150",
"statusMessageCode": 200,
"statusMessage": "transaction successfully processed",
"senderPhoneNumber": "22951010200", //Phonenumeber you speciy in your collection request
"senderFirstName": "Euler", //User firstname you specified in your collect request
"senderLastName": "Dougbe", //User lastname you specified in your collect request
"currency": "XOF", //Currency of the transaction.
"amount": 2000, //Amount of the transaction
"senderOperator": "MTN", // Mobile Money wallet operator
"startTimestampInSecond": 1638087167, // Timestamp in second of whe you init the transaction
"endTimestampInSecond": 1638087167 // Timestamp in second of when the transaction is finished
}
Disbursement callback data sample
{
"reference": "dd1e2d17-5c21-4964-b58d-198fd2aac150", // reference of the transaction Chipdeas Momo Api
"statusMessageCode": 200,
"statusMessage": "success",
"recipientPhoneNumber": "22951010200", //Phone number you specify in your deposit request
"currency": "XOF", //Currency of the transaction.
"amount": 2000, //Amount of the transaction
"senderOperator": "MTN", // Mobile Money wallet operator
"startTimestampInSecond": 1638087167, // Timestamp in second of whe you init the transaction
"endTimestampInSecond": 1638087167 //Timestamp in second of when the transaction is finished
}
More Info
Collection and disburssement parametters
- phoneNumber
parameter
You specify the phoneNumber
of a collection with method from(phoneNumber: sting)
And for a disbursement you specify phoneNumber
with method to(phoneNumber: sting)
Those methode are locking for a string containing the phone number of the money sender for collection and the money recipient for disbursement.
The PhoneNumber should respect this format:
XXXOOOOOOOO
where the three X
represent the country phone préfix (229
| 237
for example), and the O
are the phone number in the country. The number of O
can change with the country but the prefix should be 3.
- currency
parameter
You specify the currenct of a transaction with the method currency(currency: string)
The currency should be a string of 3 character.
If you add a currency that is not the currency localy used in the country of the phone number of the transaction, we will convert the amount of the transaction into local currency.
Our conversion rate evoluate like the market.
- amount
parameter
You specify the amount of a transaction with the method amount(transactionAmount: number)
It is a number.
We will check if the currency that you specify for the transaction is the local currency of the phone number's country and then we will convert the amount into local currency before perform the transaction with the customer
- fee
parameters
You specify the fee you want to add to the payer with the method setFee(fee: float, userSupportAllFees?: boolean)
The first parametter is the fee in percent you want to add.
The second parametter: userSupportAllFees
is a boolean. If it is true, we will calculate the needed payer amount to allow you to get your amount you asked + the fee you added.
Is userSupportAllFees
is false, we will juste ask the user for the amount you specify + your fees.
Ex:
.collect().amount(1000).setFee(10, false)
will get ask1100
to the user and when he confirm, we will take our fee from1100
and leave you the rest.collect().amount(1000).setFee(10, true)
will get ask1100 + ourFees
to the user and when he confirm, we will increase your account of1100
- firstName
and lastName
parameters
You respectively specify firstName
and lastName
with methods firstName(senderFirstName: string)
and lastName(senderLastName: string)
Those parametters are required to perform secured collection request.
Disbursement doesn't need them.
If you make 3 request per day with unspesified firstName
and | or lastName
we will block the 4th and the other. We recommand you to specify fisrtName
and lastName
for all your collection request.
In sandbox test, you have no probleme with firstName
and lastName
specification, you can do as you like But be careful for Live
Status Message Code
| Code | Relative Status | Meaning | |:----:| --------------- | ------------------------------------------------------------------ | | 200 | ✔️ -- success | Transaction successful | | 201 | 🕟 -- pending | Data in validation | | 202 | 🕟 -- pending | Transaction pending | | 203 | 🕟 -- pending | Data are validated, server is working | | 204 | 🕟 -- pending | Waiting for ussd push validation | | 400 | ❌ -- error | Incorrect data enter in the request | | 401 | ❌ -- error | Parameters not complete | | 402 | ❌ -- error | Payment PhoneNumber is not correct | | 403 | ❌ -- error | Deposit PhoneNumber is not correct | | 404 | ❌ -- error | Timeout in USSD PUSH/ Cancel in USSD PUSH | | 406 | ❌ -- error | Payment phoneNumber got is not for mobile money wallet | | 460 | ❌ -- error | Payer’s payment account balance is low | | 461 | ❌ -- error | An error occured while paying | | 462 | ❌ -- error | This kind of transaction is not supported yet, processor not found | | 5XX | ⛔️ -- error | An unknow error occured on the api |
Sandbox tests
You can use your test apikey
or all users test apikey : test_FOdigzgSopV8GZggZa89
to make sandbox requsts.
All valid phone number you used in sandbox will send you valid responses as it was the live mode.
For exemple, if you use the phone number 22951010581
you will get a response with status message code 201
(what means pending
see more here). Some seconds laters, you will get status messages codes 202
, 203
and 200
(200
means success).
It is the same thing for others phone number with a small exception to allow errors case handling by implementor.
| Sandbox Phone number | -> final status message code | | -------------------- | ----------------------------:| | 22951010402 | 402 | | 22951010403 | 403 | | 22951010404 | 404 | | 22951010460 | 460 | | 22951010461 | 461 | | 22951010462 | 462 | | 22951010200 | 200 |
For Live apiKey
and Live Responses requests Contact us
Limitation
Unsecured collect limitation
When you are making a collection request, you have posibility to specify or not the payer's firstName and lastname.
By not specifying firstName
and lastName
, you can make quick test.
But when firstName
and lastName
are not specified your collection request is not secured.
And you are alowed to perform at most 3 unsecured collection resquest per day. More request will be just blocked.
You cannot perform unsecured collection request for more than 500 XOF.
Contact us
Call us or write us to get your apikey and start getting payment
E-mail: [email protected] Website: https://chipdeals.me Phone: +22990630401 Whatsapp: +22990630401
Copyright (C) 2022 Chipdeals Inc - https://chipdeals.me