Issuer API

Put your credit on a phone number.

One API for another company's app: credit a Back2Buy customer by their mobile number, take it back, and read every payment they make with it at a shop in the network. The customer sees your name beside the balance, kept separate from every other kind of credit they hold.

Base URL https://api.back2buy.com/v1

Read the reference Ask for a key

One call

Every request carries your key as a bearer token. Keys are issued by the shop, shown once, and can be revoked at any time.

Credit ₹250 to a customer

curl https://api.back2buy.com/v1/credits \
  -H "Authorization: Bearer b2bn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "amountPaise": 25000,
    "requestId": "order-5512",
    "note": "Refund for order 5512"
  }'

Response · 201

{
  "id": "order-5512",
  "kind": "credit",
  "phone": "+919876543210",
  "amountPaise": 25000,
  "balancePaise": 25000,
  "at": 1760000000000,
  "replayed": false
}

Amounts are paise

Integers only. 25000 is ₹250. Never a decimal, never a string.

Numbers are E.164

+919876543210. The number is the account: no sign-up, no customer id to store.

Safe to retry

Send a requestId and a repeat of the same call moves nothing and answers replayed: true.

5,000 calls an hour

Per issuer. Over it, 429 rate_limited, and nothing is charged.

The routes

Six of them. Every one is documented in full, with Node and cURL, in the reference.

GET /v1/account Your issuer, your deposit, and whether you are switched on.

GET /v1/balance What one phone number holds of your credit.

POST /v1/credits Put credit on a number. Drawn from your deposit.

POST /v1/debits Take it back. Never below zero.

GET /v1/payments Where your credit was spent, oldest first, with a cursor.

GET /v1/movements Every movement on your account, yours and the shops'.

When something is refused

One shape for every error, with a code you can branch on rather than a sentence you would have to match.

Any failure

{
  "error": {
    "code": "insufficient_deposit",
    "message": "Your deposit is ₹120. This credit needs ₹250."
  }
}

`401 unauthenticated`

No key, a revoked key, or a key sent the wrong way.

`403 issuer_inactive`

The shop has switched your issuer off. Nothing moves until it is back on.

`400 invalid_argument`

A number that is not E.164, an amount that is not a positive integer.

`429 rate_limited`

More than 5,000 calls in an hour. Slow down and retry.

What the customer sees

Your credit appears in their Back2Buy wallet under your name, separate from the shop's own credit, and they are told the moment it arrives or is taken back. The words are Back2Buy's: a key is not a licence to send text to a customer under this name.

See how it reads