Your first integration
This guide takes one test customer through a weekly plan in the sandbox: the plan is offered, accepted, kept, put at risk and cancelled. Nothing is delivered or charged, and you don’t have to wait a week for any of it.
The examples use a savings app’s plan that starts after a first deposit and is kept by a deposit of at least ₦5,000 each week. Use the action keys and conditions from your own campaign.
-
Build a campaign and create a sandbox key. Build the plan in the dashboard and put it in test mode, so its status is
testing. Then, under Developers, create a sandbox key. Sandbox keys startaura_test_. Keep the key on your server; never put it in an app or a browser. -
Add a webhook endpoint. Under Developers, then Webhooks, add your HTTPS endpoint and copy its signing secret. Check the signature on everything that arrives, as Webhooks shows.
-
Read your campaign. Note its
id, how it starts (starts_with) and thekeyof each action.Terminal window curl https://sandbox-api.poweredbyaura.com/v1/campaigns?status=testing \-H "Authorization: Bearer $AURA_API_KEY" -
Report the action that starts the plan. Use the test number
+2348000000001, which delivers straight away.Terminal window curl https://sandbox-api.poweredbyaura.com/v1/actions \-H "Authorization: Bearer $AURA_API_KEY" \-H "Content-Type: application/json" \-d '{"reference": "test-0001","campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA","action": "first_deposit","customer_id": "CUS-204871","phone_number": "+2348000000001","occurred_at": "2026-10-20T09:40:00+01:00","value": { "amount": { "amount": 1000000, "currency": "NGN" } }}'value.amountis the deposit in kobo:1000000is ₦10,000. The answer comes back at once with201. The action earned the first week’s data, which waits for the customer to accept, and the plan isoffered:{"object": "action","reference": "test-0001","group": "offer","earned": true,"reason": null,"rewards": [{ "object": "reward", "kind": "plan_delivery", "amount_gb": 1.5, "status": "waiting_for_customer", … }],"plan": { "id": "pln_01JAC4XB7Q2W9D8M5X4N6B1C0V", "object": "plan", "status": "offered", "current_period": null },…}If your campaign starts plans by offer, send an offer instead. If
groupiscomparison, the customer is in the comparison group: report the action again with a newreferenceand a newcustomer_iduntil you get one in the offer group. -
Accept the plan. Create a plan card link from your server, open its
urlin a browser and tap Accept.Terminal window curl https://sandbox-api.poweredbyaura.com/v1/customers/CUS-204871/plan-card-links \-H "Authorization: Bearer $AURA_API_KEY" \-H "Content-Type: application/json" \-d '{ "campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA" }'Your endpoint receives
plan.started, thenreward.deliveredfor the first 1.5GB. Accepting keeps this week, so the weekly deposit is first needed next week. -
Move to next week and keep the plan. End this week, then report a weekly deposit. It earns next week’s data.
Terminal window curl https://sandbox-api.poweredbyaura.com/v1/sandbox/plans/pln_01JAC4XB7Q2W9D8M5X4N6B1C0V/advance \-H "Authorization: Bearer $AURA_API_KEY" \-H "Content-Type: application/json" \-d '{ "to": "period_end" }'Then report
weekly_depositwith a newreferenceand a deposit of at least ₦5,000, as in step 4. The answer hasearned: true, andreward.deliveredfollows. -
See the nudge and the cancellation. Move to next week again, without a deposit. Then move to the warning:
{ "to": "at_risk_warning" }sendsplan.at_risk. Move to the week’s end:{ "to": "period_end" }sendsplan.cancelled.
Every other outcome, including failed and flagged deliveries, has its own test number.
Going live
Section titled “Going live”- Make sure one test action has gone through and delivered. A campaign can go live only after that.
- Create a live key under Developers. Live keys start
aura_live_and need your business to be verified. - Point your server at
https://api.poweredbyaura.com/v1with the live key, and add your production webhook endpoint. - Set the campaign live in the dashboard. Going live needs a paid Aura plan; the sandbox is free.
© 2026 PressOne Africa Limited ·poweredbyaura.com ·Privacy ·Terms