# cards.sunshine.verify

> Published by [sunshine.cards](https://lexicon.garden/identity/did:web:sunshine.cards)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:web:sunshine.cards/cards.sunshine.verify)
- [Documentation](https://lexicon.garden/lexicon/did:web:sunshine.cards/cards.sunshine.verify/docs)
- [Examples](https://lexicon.garden/lexicon/did:web:sunshine.cards/cards.sunshine.verify/examples)

## Definitions

### `cards.sunshine.verify`

**Type**: `procedure`

Checks a tap of a Sunshine Card. Called through the scanner's PDS (service auth), it also returns a signed scan record for the caller to write into the scanner's repo.

#### Input

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ctr` | `string` | No | The read counter, in hex, from a plain-mirror tag. |
| `did` | `string` (did) | Yes | The card's creator. |
| `mac` | `string` | Yes | The tap's signature, in hex. |
| `picc` | `string` | No | The encrypted serial number and counter, in hex, from an encrypted-mirror tag. Supply exactly one of ctr and picc. |
| `uid` | `string` | Yes | The tag's serial number, in hex. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `proof` | `ref` → `#proof` | No | Write it whenever it's present, even when valid is false. When valid, it's the scan just made; when reason is alreadyCollected, it's the scanner's earlier scan of this card, signed again. |
| `reason` | `string` | No |  |
| `valid` | `boolean` | Yes |  |

#### Errors

- **CreatorUnavailable**: The creator's deck can't be reached. Retry the same tap; if that returns replayed, tap again.

### `cards.sunshine.verify#proof`

**Type**: `object`

A signed scan record, with the arguments com.atproto.repo.createRecord needs to write it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `collection` | `string` (nsid) | Yes |  |
| `did` | `string` (did) | Yes | The scanner: the repo to write to. |
| `record` | `unknown` | Yes | The signed cards.sunshine.scan record. |
| `rkey` | `string` (record-key) | Yes |  |

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "main": {
      "description": "Checks a tap of a Sunshine Card. Called through the scanner's PDS (service auth), it also returns a signed scan record for the caller to write into the scanner's repo.",
      "errors": [
        {
          "description": "The creator's deck can't be reached. Retry the same tap; if that returns replayed, tap again.",
          "name": "CreatorUnavailable"
        }
      ],
      "input": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "ctr": {
              "description": "The read counter, in hex, from a plain-mirror tag.",
              "maxLength": 6,
              "minLength": 6,
              "type": "string"
            },
            "did": {
              "description": "The card's creator.",
              "format": "did",
              "type": "string"
            },
            "mac": {
              "description": "The tap's signature, in hex.",
              "maxLength": 16,
              "minLength": 16,
              "type": "string"
            },
            "picc": {
              "description": "The encrypted serial number and counter, in hex, from an encrypted-mirror tag. Supply exactly one of ctr and picc.",
              "maxLength": 32,
              "minLength": 32,
              "type": "string"
            },
            "uid": {
              "description": "The tag's serial number, in hex.",
              "maxLength": 14,
              "minLength": 14,
              "type": "string"
            }
          },
          "required": [
            "did",
            "uid",
            "mac"
          ],
          "type": "object"
        }
      },
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "proof": {
              "description": "Write it whenever it's present, even when valid is false. When valid, it's the scan just made; when reason is alreadyCollected, it's the scanner's earlier scan of this card, signed again.",
              "ref": "#proof",
              "type": "ref"
            },
            "reason": {
              "knownValues": [
                "notGenuine",
                "replayed",
                "alreadyCollected",
                "unknownCard"
              ],
              "maxLength": 64,
              "type": "string"
            },
            "valid": {
              "type": "boolean"
            }
          },
          "required": [
            "valid"
          ],
          "type": "object"
        }
      },
      "type": "procedure"
    },
    "proof": {
      "description": "A signed scan record, with the arguments com.atproto.repo.createRecord needs to write it.",
      "properties": {
        "collection": {
          "format": "nsid",
          "type": "string"
        },
        "did": {
          "description": "The scanner: the repo to write to.",
          "format": "did",
          "type": "string"
        },
        "record": {
          "description": "The signed cards.sunshine.scan record.",
          "type": "unknown"
        },
        "rkey": {
          "format": "record-key",
          "type": "string"
        }
      },
      "required": [
        "did",
        "collection",
        "rkey",
        "record"
      ],
      "type": "object"
    }
  },
  "id": "cards.sunshine.verify",
  "lexicon": 1
}
```