Skip to content
Last updated

How to start?

When creating an account with Blu Penguin, you will first receive access to our sandbox environment. The sandbox environment is completely isolated from our production environment.

You can safely test your integration with Blu Penguin without real mobile money wallets and real money involved immediately after creating your Blu Penguin account.

Access to your production account, where live payments can be made, will be granted after completing the onboarding on your sandbox account.

Now that you have an account in our sandbox, let's look at how to start integrating.

Where is the API?

The base URL for the Blu Penguin Merchant API is different between our sandbox and production environments.

EnvironmentBase URL
Sandboxhttps://api.sandbox.transaction-monitor.io/
Productionhttps://api.transaction-monitor.io/

The specific operation can be called by appending the endpoint to the base URL.

Example: https://api.sandbox.transaction-monitor.io/v2/payouts

⚠️ Warning: The base URLs are different between sandbox and production accounts. Please store them in your application's environment-specific configuration.

Where is the Blu Penguin Dashboard?

From the Blu Penguin Dashboard you can:

  • Set up callback URLs
  • Generate an API token
  • See all accepted payments
  • See financial statements
  • Invite users
  • Control access levels
  • And much more

As our sandbox environment is completely isolated from our production environment, the URLs to access the Blu Penguin dashboard are different.

EnvironmentDashboard URL
Sandboxhttps://dashboard.sandbox.transaction-monitor.io/
Productionhttps://dashboard.transaction-monitor.io/

How to authenticate calls to the Merchant API

The Blu Penguin Merchant API uses a bearer token for authentication. An authorization header is required for all calls to the Blu Penguin Merchant API.

The token can be generated from the Blu Penguin Dashboard. Instructions on how to do that can be found in the Blu Penguin Dashboard Docs.

Below is an example payout request with curl:

curl -i -X POST \
https://api.sandbox.transaction-monitor.io/payouts \
-H 'Authorization: Bearer <YOUR_API_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"payoutId": "33f30946-881d-40bc-8ca2-94aa4cd467ac",
"amount": "15",
"currency": "ZMW",
"recipient": {
    "type": "MMO",
    "accountDetails": {
        "phoneNumber": "260763456789",
        "provider": "MTN_MOMO_ZMB"
        }
    }
}'

⚠️ Warning: The API tokens are different between sandbox and production accounts. When moving from sandbox to production a new API token must be generated from the production Blu Penguin Dashboard. Please store the API token in your application's environment specific secure storage.

💡 Tip: If you are looking to add a second layer of security, you can implement Signatures to ensure security even if your API token should leak.

Setting up callbacks

As the Blu Penguin API is asynchronous, we recommend implementing a callback handler in your application to find out about the final status of your payments as soon as they are processed.

You can read more about how to do that from the Blu Penguin Dashboard docs.

When configured, we will send you a callback with the final status of a payment to your configured callback URL. Read more about callbacks.

Starting to build the integration

Now you are all set to integrate with the Blu Penguin Merchant API.

  • Play in Postman - Test and get a feel for the API using our Postman collection.
  • Deposits - Find out how to integrate to the API to get paid.
  • Payouts - Find out how to integrate to send money.
  • Refunds - Find out how to handle refunds.
  • Payment page - Find out how to get paid, with an out-of-the-box payment experience.

Testing the integration

You can test the Blu Penguin Merchant API and Dashboard with your sandbox account right after signing up. You do not need to go through the onboarding process for that since no real money is involved.

There are special phone numbers available to simulate successful and different failure cases.

ℹ️ Info: It is not possible to see the authorization flows (i.e. entering the PIN prompt) in sandbox.

Here's a few helpful resources to get everything you need to start integrating and testing.

  • Providers - Find all the different providers currently available on Blu Penguin.
  • Test phone numbers - Here's all the test numbers you can use on your sandbox account to test different payment scenarios.
  • Failure codes - Here's a summary of all the different payment failure codes you might encounter. They are all of course documented in the API reference as well.
  • Brand guidelines - Find the brand guidelines on how to use provider logos.
 
Next page