Card provisioning

The Card Provisioning API lets wallet providers attach a customer's PAN or account number to their wallet profile. Once provisioned, the wallet can list the card in its UI, route purchases to it without re-prompting the customer, and offer multi-card management (default card, blocked card, etc.).

This is a separate API surface from the Remote API. The Remote API is the runtime payment engine; the Provisioning API is the wallet-management layer that runs alongside it.

For the rules, see Card Provisioning — business rules.

Base URLs

All operations are POST and authenticated using the same Basic-Auth or Bearer credentials as the Remote API. See Authentication.

The provisioning lifecycle

                       ┌────────────┐
   customer adds card  │            │     customer removes card
   ───────────────────►│   LINKED   │◄─────────────────────────
                       │            │       /delink
                       └─────┬──────┘
                             │
                             │  customer reports card
                             │  lost or stolen
                             ▼
                       ┌────────────┐
                       │            │     customer recovers
                       │  BLOCKED   │     ───────────────►  back to LINKED
                       │            │       /unblock
                       └────────────┘

Plus two intermediate states for the registration flow itself:

• COSMETIC — provisional state when the wallet wants to display the card before validation
• DELINKED — terminal state after /delink

The seven operations

Register

Links a PAN or account number to a wallet identified by MSISDN.

Request fields:

Request:

curl -X POST https://qa.scantopay.io/pluto/provisioning/register \
  -u 'wallet_username:wallet_password' \
  -H 'Content-Type: application/json' \
  -d '{
    "msisdn": "27832006283",
    "accountNumber": "5221008264807699",
    "account": "30",
    "cardholderName": "J Smith",
    "expiryDate": "1228",
    "state": "LINKED",
    "node": "SBSA",
    "validationMethod": "SIMPLE",
    "dateOfBirth": "19830711"
  }'

Response:

{ "result": "SUCCESS" }

Possible result values:

Delink

Removes a card from a wallet permanently. To re-add it, call /register again.

curl -X POST https://qa.scantopay.io/pluto/provisioning/delink \
  -u 'wallet_username:wallet_password' \
  -H 'Content-Type: application/json' \
  -d '{
    "msisdn": "27832006283",
    "accountNumber": "5338921234567891"
  }'

Response:

{ "result": "SUCCESS" }

Returns FAIL if the (msisdn, accountNumber) pair doesn't match a wallet record.

Block

Temporarily disables a card without delinking. Use when a customer reports a card lost / stolen and you don't want to lose the card-to-wallet association for the post-recovery flow.

curl -X POST https://qa.scantopay.io/pluto/provisioning/block \
  -u 'wallet_username:wallet_password' \
  -H 'Content-Type: application/json' \
  -d '{
    "msisdn": "27832006283",
    "accountNumber": "5338921234567891"
  }'

Returns SUCCESS or FAIL.

Unblock

Reverses a Block. Card transitions from BLOCKED back to LINKED.

curl -X POST https://qa.scantopay.io/pluto/provisioning/unblock \
  -u 'wallet_username:wallet_password' \
  -H 'Content-Type: application/json' \
  -d '{
    "msisdn": "27832006283",
    "accountNumber": "5338921234567891"
  }'

Returns SUCCESS or FAIL.

Update

Updates mutable fields on an existing link: expiryDate, imageId, cardholderName. At least one of these must be supplied.

curl -X POST https://qa.scantopay.io/pluto/provisioning/update \
  -u 'wallet_username:wallet_password' \
  -H 'Content-Type: application/json' \
  -d '{
    "msisdn": "27832006283",
    "accountNumber": "5338921234567891",
    "expiryDate": "1230",
    "imageId": 12345,
    "cardholderName": "Mr J Smith"
  }'

node, validationMethod, and state cannot be updated — those are register-time-only.

Possible result values are the same set as Register, plus:

• CARD DELINKED — the card has been delinked; Update doesn't resurrect it. Re-register instead.

Check Card Status

Returns the card's current provisioning state.

curl -X POST https://qa.scantopay.io/pluto/provisioning/checkCardStatus \
  -u 'wallet_username:wallet_password' \
  -H 'Content-Type: application/json' \
  -d '{
    "msisdn": "27832006283",
    "accountNumber": "5338921234567891"
  }'

Response:

{ "result": "ACTIVE" }

Send Brand Indicator

Uploads card art that will display in the wallet UI when this card is shown. Returns an imageId you pass on subsequent /register or /update calls.

curl -X POST https://qa.scantopay.io/pluto/provisioning/sendBrandIndicator \
  -u 'wallet_username:wallet_password' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "ABC Bank Gold Card",
    "image": "<base64-encoded-image-bytes>"
  }'

Response:

{ "imageId": 12345 }

imageIds are scoped to your wallet provider. You can have many active brand indicators (one per card product / tier).

Putting it together — a registration flow

1. Customer enters card in wallet UI
   ↓
2. Wallet calls /binLookup (Remote API) to discover required fields
   ↓
3. Wallet collects fields (CVV, DOB, etc.) the BIN requires
   ↓
4. Wallet calls /register with the collected data
   ├─► SUCCESS → display card in wallet, ready to use
   ├─► ALREADY LINKED → show "this card is registered to another wallet" message
   └─► other error → handle per the result table above

If you used validationMethod: SIMPLE or DOB, the customer will be prompted by Scan to Pay's validation flow (in the wallet app's WebView or via SMS, depending on your integration) before the state transitions from COSMETIC to LINKED. If no validationMethod was sent, the card is immediately LINKED.

What's next

• Rules governing provisioning → Card Provisioning — business rules
• Use a provisioned card to pay → Purchase flow
• All Remote API endpoints → Remote API overview
• Authentication setup → Authentication