About Moneywave
Moneywave is a payment system that allows you to securely charge cards and pay accounts. Here you’ll find detailed information about our APIs – what they’re for, how to use them and when to use them. If you have any questions or comments, feel free to drop us a message at getstarted@flutterwavego.com
Getting started
Base URL: https://moneywave.herokuapp.com/
Payments in test environment
Please note that that when working in TEST environment and you need to do an account based transaction, you will need to use one of our Test Account numbers. However, because Moneywave uses 3DSecure for authentications, you have to use a live card while you are in TEST environment so you can have an idea of how it will work when you go LIVE. For those of you that will be testing on an API level, we suggest that you do your tests with a small amount of money because you will not be able send the money to a real bank account number.
Test account details:
Bank Code: 044
Bank Accounts: 0690000004, 0690000005
Bank Code: 058
Bank Account: 0921318712
Moneywave uses 3DSecure for authenticating Mastercards and Visa Cards. We return a response code "02" and a response html as well as an auth url parameter when the charge call is initiated. For validation, you are supposed to either load the response html in an iFrame / Browser or Redirect your users to the auth url to validate the transaction. When this has been done, we will redirect to the response url you supplied in the first call and then pass our response as a query parameter.
Moneywave uses PIN for authenticating Verve Cards. You need to include the pin parameter to your request payload and then validate the transaction using a One Time password that will be sent to the cardholders phone.
Step 1. Create an account
First, you’ll need to create an account with us. To do that, you need to go to https://moneywave.flutterwave.com to create your account. Once successfully created you will get an apiKey and secret with credentials for your sandbox and production environments. These credentials will be availble under account settings, when you are logged in to the portal. To get your LIVE credentials, you need to Toggle the TEST LIVE button and fill up the GO LIVE form.
Step 2. Get a list of all banks A lot of the time, when using the moneywave API, you’ll be required to enter a 3 - character bank code used to identify a bank. You can get this list of banks by calling the /banks endpoint. We’ll really recommend that you send a post request to this end point and save the response in a variable before you call any other endpoint when using Moneywave. A sample request could look something like this [POST] /banks
{ "status": "success", "message": "Banks fetched", "data": { "100": "SunTrust Bank", "214": "First City Monument Bank", "215": "Unity Bank", ...... "403": "SafeTrust Mortgage Bank", "501": "Fortis Microfinance Bank", "044": "Access Bank", "068": "Standard Chartered Bank" } }
Step 3. Create your access token
Once you have a merchant account, you need to call /v1/merchant/verify to obtain an access token. The token represents you as a merchant and grants you access to every other endpoint. Please note that the tokens expire after 2hrs.
The parameters you might need are
Field Name
- apiKey
- secret
Field Type
- String
- String
Description
- the apiKey of the merchant
- the secret of the merchant
A sample request could look something like this [POST] /v1/merchant/verify
{ "apiKey": String, "secret": String }
A sample response looks something like this
{ status: "success", token: "" // a valid merchant token }
Step 4. Authenticate your request
Now you have your access token, all that’s left is to authenticate your API requests. To do that you need to ensure that for all your authorisation requests, you’re passing your access token in the request header.
The parameters you might need are
Field Name
- Authorization
Field Type
- String
Description
- this is the token you must have gotten from the /v1/merchant/verify endpoint
- Always ensure you do all your testing on https://moneywave.herokuapp.com, as all requests to the Live base url - https://live.moneywaveapi.co/ will be charged to your account.
- If you are getting ready to launch into production, please send us an email at customersuccess@flutterwave.com.
- All our API responses are formatted using JSON and are served over HTTPS to ensure data privacy. Please note that HTTP is not supported
- Every request you pass to us must include an access_token that has a request data included in the body.
- A success status on our response does not always mean that the payment was successful, it most probably simply means that we were able to make an attempt in processing the payment. This means that you as a customer have to ensure that you check the content of the data returned for the proper response.
- We use standard error codes in our responses for successes and failures. If you encounter any issues feel free to contact us or check out our Error messages FAQ page for more information
Features
The parameters you might need are
Field Name
- firstname
- lastname
- phonenumber
- recipient
- recipient_id
- recipient_bank
- recipient_account_number
- recipients
- card_no
- cvv
- pin
- expiry_year
- expiry_month
- apiKey
- amount
- fee
- redirecturl
- medium
- chargeCurrency
- disburseCurrency
- charge_with
- card_last4
- card_token
- sender_account_number
- sender_bank
- passcode
- card_id
- cycle
- startDate
- endDate
Field Type
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- Number
- Number
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
Description
- the firstname of the sender
- the lastname of the sender
- the phone number of the sender, must be international format starting with +
- the email of the sender
- (optional) recipient type: account, wallet, beneficiary, bulk-account
- (optional) recipient type id
- bank to send money to
- account number of the recipient in the recipient bank
- (optional) array of recipients
- card number to charge
- cvv of the card to charge
- (optional) Card PIN required when charging Verve Cards
- expiry year of the card to charge
- expiry month of the card to charge
- your merchant apiKey displayed to you after registering as a merchant.
- this is the amount to send to the beneficiary
- the amount the merchant wants to add as his commission
- the url to redirect to after transaction has been successfully validated
- this can either be web or mobile or depending on request medium
- (optional) - this is the currency in which card will be charged
- (optional) - this is the currency in which account will be credited
- (optional) - charge method : card, account, token or tokenized_card
- (optional)* - card last 4 digits, required in charge with token
- (optional)* - card token, required in charge with tokenized card
- (optional)* - charge source, required in charge with account
- (optional)* - charge source bank, required in charge with account
- (optional)* - Account Security PIN required for account charge
- (optional)* - card ID required when charging with token
- (optional)* - sheduled / recurring transfer cycle
- (optional)* - sheduled / recurring start date
- (optional)* - sheduled / recurring end date
A sample request could look something like this [POST] /v1/transfer
{ "firstname": String, "lastname": String, "phonenumber": String, "email": String, "recipient_bank": String, "recipient_account_number": String, "card_no": String, "cvv": String, "expiry_year": String, "expiry_month": String, "apiKey": String, "amount": Number, "fee": Number, "redirecturl": String, "medium": String }
{ status: "success", data: { transfer: {}, //transfer object responsehtml: "" // } }
{ status: "error", code: "INVALID_FIRSTNAME | INVALID_CARD | INVALID_LASTNAME", message: "" } OR HTTPS/1.1 401 Unauthorized { status: "error" }
{ "transactionRef": "", //Flutterwave reference from /v1/transfer call "otp": "", }
{ status: "success", data: { } //this is the transfer object }
{ "transactionRef": "", //Flutterwave reference from /v1/transfer call "authType": "", //OTP or ACCOUNT_CREDIT "authValue": "", }
{ status: "success", data: { } //this is the transfer object }
The parameters you might need are
Field Name
- firstname
- lastname
- phonenumber
- recipient
- card_no
- cvv
- expiry_year
- expiry_month
- apiKey
- amount
- fee
- redirecturl
- medium
- chargeCurrency
- disburseCurrency
- charge_with
- card_last4
- sender_account_number
- sender_bank
Field Type
- String
- String
- String
- String
- String
- String
- String
- String
- String
- String
- Number
- Number
- String
- String
- String
- String
- String
- String
- String
- String
Description
- the firstname of the sender
- the lastname of the sender
- the phone number of the sender, must be international format starting with +
- the email of the sender
- recipient should be set to "wallet"
- card number to charge
- cvv of the card to charge
- expiry year of the card to charge
- expiry month of the card to charge
- your merchant apiKey displayed to you after registering as a merchant.
- this is the amount to send to the beneficiary
- the amount the merchant wants to add as his commission
- the url to redirect to after transaction has been successfully validated
- this can either be web or mobile or depending on request medium
- (optional) - this is the currency in which card will be charged
- (optional) - this is the currency in which account will be credited
- (optional) - charge method : card, account or token
- (optional)* - card last 4 digits, required in charge with token
- (optional)* - charge source, required in charge with account
- (optional)* - charge source bank, required in charge with account
A sample request could look something like this [POST] /v1/transfer
{ "firstname": String, "lastname": String, "phonenumber": String, "email": String, "recipient": String, "card_no": String, "cvv": String, "expiry_year": String, "expiry_month": String, "apiKey": String, "amount": Number, "fee": Number, "redirecturl": String, "medium": String, }
{ status: "success", data: { transfer: {}, //transfer object responsehtml: "" // } }
{ status: "error", code: "INVALID_FIRSTNAME | INVALID_CARD | INVALID_LASTNAME", message: "" } OR HTTPS/1.1 401 Unauthorized { status: "error" }
The parameters you might need are
Field
- amount
- fee
Field
- Number
- Number
Description
- the amount you want us to send to the recipient
- the fee you want to add ad your commission as a merchant
{ "amount": Number, "fee": Number }
{ status: "success", data: { amountToSend: , //the total amount we will send to the recipient amountChargeable: , // the total amount we will charge the card merchantCommission: // your commission } }
The parameters you might need are
Field Name
- lock
- amount
- bankcode
- accountNumber
- currency
- senderName
- ref
Field Type
- String
- Number
- String
- String
- String
- String
- String
Description
- the password of your wallet
- the amount to send to the beneficiary
- the bankcode of the bank to send money to
- the account number of the recipient
- the currency to send money in
- the name of the sender
- unique transaction ref
A sample request could look something like this [POST] /v1/disburse
{ "lock": String, "amount": Number, "bankcode": String, "accountNumber": String, "currency": String, "senderName": String, "ref": String }
{ "status": "success", "data": { "data": { "responsecode": "00", "responsemessage": "Approved Or Completed Successfully", "uniquereference": "TMW000000317" }, "status": "success" } }
{ status: "error", code: "", message: "" } OR HTTPS/1.1 401 Unauthorized { status: "error" }
The parameters you might need are
A sample request could look something like this [POST] /v1/disburse/bulk
{ "lock":"539935", "recipients": [ { "amount":100, "bankcode":"044", "accountNumber":"0690000005", "ref":"7" }, { "amount":200, "bankcode":"044", "accountNumber":"0690000006", "ref":"8" } ], "currency": "NGN", "senderName": "THRIVE", "ref":"46" }
{ "status": "success", "failed": 0, "passed": 2, "data": [ { "accountNumber": "0690000005", "data": { "responsecode": "00", "responsemessage": "Approved Or Completed Successfully", "uniquereference": "TMW000000311" } }, { "accountNumber": "0690000006", "data": { "responsecode": "00", "responsemessage": "Approved Or Completed Successfully", "uniquereference": "TMW000000312" } } ] }
{ status: "error", code: "", message: "" } OR HTTPS/1.1 401 Unauthorized { status: "error" }
Resources
The parameters you might need are
Field Name
- account_number
- bank_code
Field Type
- String
- String
Description
- the account number of the sender
- the bank code of the account to resolve
{ "account_number": String, "bank_code": String }
{ status: "success", data: { } }
The parameters you might need are
Field Name
- card_no
- expiry_year
- expiry_month
- cvv
Field Type
- String
- String
- String
- String
Description
- card number of debit card
- expiry year of debit card
- expiry month of debit card
- cvv of debit card
{ "card_no": String, "expiry_year": String, "expiry_month": String, "cvv": String }
{ "status": "success", "data": { "cardToken": "be711fe2be4edb35cc554fc6428b1f64" } }
The parameters you might need are
Field Name
- id
- recipient_account_number
- recipient_bank
Field Type
- String
- String
- String
Description
- id of a successfully charged transfer.
- (optional) disburse destination account number
- (optional) disburse destination bank
{ "id": String, "recipient_account_number": String, "recipient_bank": String }
{ "status": "success", "message": "Disburse Successful", "data": { } }
{ status: "success", data: { } //this is the transfer object }
{ "ref": "2" }
{ status: "success", data: { } //this is the transfer object }
{ status: "success", data: { } //this is the transfer object }
HTTPS/1.1 400 Bad Request { status: "error", code: "INVALID_ID", message: "" } HTTPS/1.1 401 Unauthorized { status: "error" } HTTPS/1.1 404 Not found { status: "error" }