Getting started

This page shows you how to make your first authenticated request.

1. Get an API key

Create an API key from your dashboard:

• Sandbox (test keys) → dashboard-sandbox.spendfigo.com
• Production (live keys) → dashboard.spendfigo.com

Keys are environment-scoped:

• sk_test_… — test environment. No real money moves.
• sk_live_… — live environment. Real money moves.

Treat the key like a password. We show it one time, when you create it. Keep it in your secrets manager. For more data, see Authentication.

Then set your base URL for that environment:

A sandbox account is usable the moment you create it. There is no business verification to wait on — that question only has an answer where real money moves, so in sandbox your merchant is active immediately and your first key works straight away.

2. Make your first call

The smallest request there is. It answers from your key alone, touching no database and no payment rail:

curl {BASE_URL}/v1/ping \
  -H "x-api-key: sk_test_your_key_here"

{
  "code": 200,
  "message": "pong",
  "data": { "merchant_id": "mrc_…", "name": "Acme Inc." }
}

Then fetch your merchant profile:

curl {BASE_URL}/v1/merchant/me \
  -H "x-api-key: sk_test_your_key_here"

A successful response uses the standard envelope:

{
  "code": 200,
  "message": "Merchant fetched successfully",
  "data": {
    "id": "mrc_…",
    "name": "Acme Inc.",
    "slug": "acme"
  }
}

A 401 Unauthorized response tells you that the key is absent, incorrect, or revoked.

3. Discover what you can do

List your corridors. A corridor is a country you can collect money from, or pay money to. The response gives the methods and the limits for each one:

curl {BASE_URL}/v1/corridors \
  -H "x-api-key: sk_test_your_key_here"

{
  "code": 200,
  "message": "Corridors fetched successfully",
  "data": [
    {
      "country": "NG",
      "country_name": "Nigeria",
      "collection": {
        "supported": true,
        "methods": [
          { "type": "bank", "name": "Bank Transfer", "currency": "NGN", "min_amount": 100, "max_amount": 2000000 }
        ]
      },
      "payout": {
        "supported": true,
        "methods": [
          { "type": "bank", "name": "Bank Transfer", "currency": "NGN", "min_amount": 100, "max_amount": 2000000 }
        ]
      }
    }
  ]
}

Making test money move

In sandbox no money moves for real, so nothing happens on its own — there is no payer at a bank, and no bank on the other end of a payout. You decide when money lands, and whether it lands at all.

Open a collection as you normally would, then settle it:

curl -X POST https://devapi.spendfigo.com/v1/sandbox/collections/{id}/settle \
  -H "x-api-key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"outcome": "success"}'

Payouts work the same way, and need it for the same reason — nothing finishes one for you:

curl -X POST https://devapi.spendfigo.com/v1/sandbox/payouts/{id}/settle \
  -H "x-api-key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"outcome": "success"}'

Everything downstream then happens for real: your balance moves, your webhook fires, and a payment link records the payment.

Send {"outcome": "failed"} to rehearse money that does not arrive. Do this at least once, in both directions. An integration that has only ever seen a payment succeed has not been tested, and the day it matters is not the day to find out what your code does with a failure.

Rates in sandbox are fixed, so a test you write today gives the same answer tomorrow.

What sandbox cannot do

Almost everything behaves as it does in production. Two things do not, and it is cheaper to know now than to debug:

4. Next steps

• Read the money model. It explains the USD balance, corridors, and currency exchange.
• Read the conventions. They apply to every endpoint.
• Use the corridors from the step above to start a collection or a payout.