Skip to content

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.

  1. 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 start aura_test_. Keep the key on your server; never put it in an app or a browser.

  2. 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.

  3. Read your campaign. Note its id, how it starts (starts_with) and the key of each action.

    Terminal window
    curl https://sandbox-api.poweredbyaura.com/v1/campaigns?status=testing \
    -H "Authorization: Bearer $AURA_API_KEY"
  4. 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.amount is the deposit in kobo: 1000000 is ₦10,000. The answer comes back at once with 201. The action earned the first week’s data, which waits for the customer to accept, and the plan is offered:

    {
    "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 group is comparison, the customer is in the comparison group: report the action again with a new reference and a new customer_id until you get one in the offer group.

  5. Accept the plan. Create a plan card link from your server, open its url in 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, then reward.delivered for the first 1.5GB. Accepting keeps this week, so the weekly deposit is first needed next week.

  6. 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_deposit with a new reference and a deposit of at least ₦5,000, as in step 4. The answer has earned: true, and reward.delivered follows.

  7. See the nudge and the cancellation. Move to next week again, without a deposit. Then move to the warning: { "to": "at_risk_warning" } sends plan.at_risk. Move to the week’s end: { "to": "period_end" } sends plan.cancelled.

Every other outcome, including failed and flagged deliveries, has its own test number.

  1. Make sure one test action has gone through and delivered. A campaign can go live only after that.
  2. Create a live key under Developers. Live keys start aura_live_ and need your business to be verified.
  3. Point your server at https://api.poweredbyaura.com/v1 with the live key, and add your production webhook endpoint.
  4. Set the campaign live in the dashboard. Going live needs a paid Aura plan; the sandbox is free.