Quickstart

Create a test key, get a token, make a collection and receive the webhook.

You need a business account on the developer console. The console is where you create keys and register webhooks.

The examples use $API for the test base URL and $TOKEN for an access token.

Create a test key

In the console, open API keys and create a key in the test environment. Copy the client ID and the client secret. The secret is shown once.

Get a token

curl -X POST "$API/v1/oauth/token" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "resource=ismartpay"

Put access_token from the response in $TOKEN. It lasts 5 minutes. See Authentication.

Make a collection

Use a test number from Sandbox.

curl -X POST "$API/v1/collections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042",
    "amount": "120.00",
    "currency": "GHS",
    "provider": "telecel",
    "payer": { "type": "msisdn", "value": "233000000001" }
  }'

The response is 202. The payment is not finished yet.

Check its status

curl "$API/v1/collections/order-1042" \
  -H "Authorization: Bearer $TOKEN"

The status starts as accepted and moves through dispatched while the payer approves. It ends as settled, failed or expired. See Payment statuses.

Receive the webhook

Register an HTTPS endpoint under Webhooks in the console. When the collection changes state, iSmartPay sends a signed POST to it. Verify the signature before you trust it. See Webhooks.

If something fails

401: the token is missing, wrong or expired. Get a new one.
403: the key may not do this, or you used a key in the wrong environment.
409: you reused an Idempotency-Key with a different body. See Idempotency and references.
429: slow down and wait for Retry-After.