{
  "info": {
    "_postman_id": "6d1b1f4e-2f7a-4c55-9b0e-6a4a1c1f3e10",
    "name": "Nimbuu API v1",
    "description": "Loyalty points and stamps for cafes and salons.\n\n## Keys and the sandbox\n\nSend `Authorization: Bearer <key>`. Secret keys (`sk_live_`, `sk_test_`) are for your server.\nPublishable keys (`pk_live_`, `pk_test_`) can be used in a browser and can do less. Test keys use\nthe sandbox: phone numbers are +91 00000 and any five digits, and the OTP code is always 000000.\n\n## Idempotency\n\nEvery POST needs an `Idempotency-Key` header, 1 to 255 characters, not starting with `nimbu:`,\n`dash:`, `staff:` or `seed:` (kept for Nimbuu). Sending the same key and body again returns the\nfirst result (with `Idempotent-Replayed: true`) and writes nothing new. A retry must send the\nsame body: the same key with a different body (a missing or new `otp_verification` included) is\n409 `idempotency_conflict`.\n\n## OTP limits\n\nCodes go only to Indian numbers (+91 and 10 digits); any other number gets 422\n`phone_not_supported`. Per business, phone and purpose: one code per 45 seconds, 5 an hour and 10\na day. Across all businesses, a phone gets at most 20 codes an hour and 50 a day through secret\nkeys, and the same again through publishable keys, which also get at most 30 codes an hour and\n100 a day per client IP address, and at most 100 codes an hour and 500 a day per business.\nThrough secret keys and the counter app together, a shop sends at most 100 codes a day while it is\nnew (and all new shops together 1,000), and 2,000 once Nimbuu has checked it. Only codes that are\nsent count: a refused call or a failed send uses up nothing. Every limit answers 429\n`otp_rate_limited`.\n\n## Browsers\n\nThe routes a publishable key may call (`POST /v1/members`, `GET /v1/members/{id}` and its\ntransactions, `GET /v1/rewards`, `POST /v1/otp/send` and `POST /v1/otp/verify`) answer CORS\nrequests from any website, without cookies. Earn, redeem and reverse don't, and a secret key sent\nfrom a web page on another site is refused with 403 `not_allowed`. Keep secret keys on your\nserver.\n\n## Errors\n\nEvery error is `{\"error\": {\"code\": ..., \"message\": ...}}`. A `validation_error` adds `fields`.\nEvery 429 (`rate_limited`, `otp_rate_limited`) adds `retry_after`, the seconds to wait, which is\nalso sent as the `Retry-After` header.\n\n## Rewards\n\n`available_rewards` and `reward.unlocked` look at the balance, whether the reward is switched on,\nand its dates. Limits per member and in total are checked only when you redeem.\n\n## Webhooks\n\nEvents: `member.created`, `points.earned`, `reward.unlocked`, `reward.redeemed` and\n`points.expiring`. Each is a POST with a JSON body: `id` (`evt_...`), `type`, `created_at`,\n`livemode` and `data`. Payloads hold ids only; call `GET /v1/members/{id}` for details.\n\nTo check a webhook:\n\n1. Read the header `Nimbuu-Signature: t=<unix time>,v1=<hex>`.\n2. Work out HMAC-SHA256 of `<t>.<raw body>` with your endpoint secret (`whsec_...`) and compare\n   it with `v1` in constant time.\n3. Refuse it if `t` is more than 5 minutes away from now.\n4. Use `Nimbuu-Event-Id` to skip events you have already handled: one event can arrive twice.\n\nAnswer with any 2xx within 10 seconds. Anything else is tried again after 1 minute, 5 minutes,\n30 minutes, 2 hours, 6 hours and 24 hours, then given up. Redirects are not followed.\n",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{secret_key}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://nimbuu.in"
    },
    {
      "key": "secret_key",
      "value": "sk_test_..."
    }
  ],
  "item": [
    {
      "name": "Create or find a member",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}"
          }
        ],
        "url": {
          "raw": "{{base_url}}/v1/members",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "members"
          ],
          "variable": [],
          "query": []
        },
        "description": "Gives the phone number a card at this business, or returns the card it already has (200). Name, consent and language are only used when the member is created. Publishable keys must send an otp_verification for purpose member_access and get a member_token back. With create false it only finds: a phone with no card here answers 200 with {\"found\": false}, writes nothing and is not remembered, so the same otp_verification can then create the card once the customer has seen your notice.",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"phone\": \"+910000012345\",\n  \"name\": \"Asha\",\n  \"message_consent\": true\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      }
    },
    {
      "name": "Earn",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}"
          }
        ],
        "url": {
          "raw": "{{base_url}}/v1/earn",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "earn"
          ],
          "variable": [],
          "query": []
        },
        "description": "Adds points for a bill (points programs), or stamps or a visit. The program's cap per bill applies.",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"member_id\": \"mem_8f14e45fceea167a5a36dedd4bea2543\",\n  \"bill_amount_paise\": 25000,\n  \"bill_id\": \"B-1042\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      }
    },
    {
      "name": "List rewards",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{base_url}}/v1/rewards",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "rewards"
          ],
          "variable": [],
          "query": []
        },
        "description": "Active rewards inside their validity window, cheapest first."
      }
    },
    {
      "name": "Send an OTP",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}"
          }
        ],
        "url": {
          "raw": "{{base_url}}/v1/otp/send",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "otp",
            "send"
          ],
          "variable": [],
          "query": []
        },
        "description": "Sends a 6-digit code to the customer's phone, valid for 5 minutes. Purpose redeem confirms a redemption, member_access lets a publishable key create or read a member. In the sandbox the code is always 000000 and nothing is sent. Only Indian numbers (+91) get codes; others are 422 phone_not_supported. Limits are in the API description.",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"purpose\": \"redeem\",\n  \"member_id\": \"mem_8f14e45fceea167a5a36dedd4bea2543\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      }
    },
    {
      "name": "Verify an OTP",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}"
          }
        ],
        "url": {
          "raw": "{{base_url}}/v1/otp/verify",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "otp",
            "verify"
          ],
          "variable": [],
          "query": []
        },
        "description": "Checks the code. Returns an otp_verification token for the redeem or member call it confirms: single use, valid for 10 minutes. Each code allows 5 tries.",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"purpose\": \"redeem\",\n  \"member_id\": \"mem_8f14e45fceea167a5a36dedd4bea2543\",\n  \"code\": \"000000\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      }
    },
    {
      "name": "Redeem",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}"
          }
        ],
        "url": {
          "raw": "{{base_url}}/v1/redeem",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "redeem"
          ],
          "variable": [],
          "query": []
        },
        "description": "Spends points on a reward, or a raw number of points. Needs an otp_verification (purpose redeem) for raw points and for rewards that require an OTP. A retry must send the same body, the same otp_verification included: a different body under the same Idempotency-Key is 409 idempotency_conflict.",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"member_id\": \"mem_8f14e45fceea167a5a36dedd4bea2543\",\n  \"reward_id\": \"rwd_c9f0f895fb98ab9159f51fd0297e236d\",\n  \"otp_verification\": \"otpv_...\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      }
    },
    {
      "name": "Reverse a transaction",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{$guid}}"
          }
        ],
        "url": {
          "raw": "{{base_url}}/v1/transactions/:transaction_id/reverse",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "transactions",
            ":transaction_id",
            "reverse"
          ],
          "variable": [
            {
              "key": "transaction_id",
              "value": "",
              "description": "txn_..."
            }
          ],
          "query": []
        },
        "description": "Undoes an earn or a redeem in full, for example after a refund. The balance may go below 0 if the points were already spent.",
        "body": {
          "mode": "raw",
          "raw": "{}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      }
    },
    {
      "name": "Get a member",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Nimbuu-Member-Token",
            "value": "",
            "description": "Publishable keys only: the member_token from POST /v1/members.",
            "disabled": true
          }
        ],
        "url": {
          "raw": "{{base_url}}/v1/members/:member_id",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "members",
            ":member_id"
          ],
          "variable": [
            {
              "key": "member_id",
              "value": "",
              "description": "mem_..."
            }
          ],
          "query": []
        },
        "description": "Balance, unit and the rewards the balance covers."
      }
    },
    {
      "name": "List a member's transactions",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Nimbuu-Member-Token",
            "value": "",
            "description": "Publishable keys only: the member_token from POST /v1/members.",
            "disabled": true
          }
        ],
        "url": {
          "raw": "{{base_url}}/v1/members/:member_id/transactions",
          "host": [
            "{{base_url}}"
          ],
          "path": [
            "v1",
            "members",
            ":member_id",
            "transactions"
          ],
          "variable": [
            {
              "key": "member_id",
              "value": "",
              "description": "mem_..."
            }
          ],
          "query": [
            {
              "key": "cursor",
              "value": "",
              "description": "The pagination cursor value.",
              "disabled": true
            },
            {
              "key": "limit",
              "value": "",
              "description": "Number of results to return per page.",
              "disabled": true
            }
          ]
        },
        "description": "Newest first. Follow `next` for older entries. `limit` is 1 to 100 (default 20)."
      }
    }
  ]
}
