Copy page

Electronic Signatures

OTP Verification & Proof

Deep dive into the OTP validation flow, proof certificate format, and eIDAS compliance details.

OTP flow

Each signer goes through this sequence:

Code
1. Initiate  →  System sends OTP via SMS to signer's phone
2. Validate  →  Signer enters 6-digit OTP code
3. Sign      →  Signer draws their signature on the document
4. Complete  →  Signature embedded in PDF with certificate

OTP rules

Parameter	Value
OTP length	6 digits
Validity	5 minutes from sending
Max attempts	3 per OTP
Resend cooldown	60 seconds
Delivery	SMS to signer's registered mobile phone

Validate an OTP

The signer's application calls:

Code
curl -X POST https://api.faireplace.com/api/leases/{lease_id}/signature/validate-otp \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
    "otp": "482916"
  }'

Code
{
  "success": true,
  "message": "Signature completed successfully",
  "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
  "signer_status": "COMPLETED",
  "document_status": "SIGNING",
  "remaining_signers": 1,
  "signed_pdf_url": null
}

Resend an OTP

If the OTP expires or the signer didn't receive it:

Code
curl -X POST https://api.faireplace.com/api/leases/{lease_id}/signature/resend/{signer_type} \
  -H "Authorization: Bearer $API_KEY"

The previous OTP is invalidated when a new one is sent.

OTP error handling

Wrong OTP code

Code
{
  "error": {
    "code": 422,
    "type": "VALIDATION_ERROR",
    "message": "Invalid OTP code",
    "details": {
      "attempts_remaining": 2,
      "expires_at": "2026-02-20T14:35:00Z"
    }
  }
}

OTP expired

Code
{
  "error": {
    "code": 422,
    "type": "OTP_EXPIRED",
    "message": "OTP has expired. Request a new one.",
    "details": {
      "expired_at": "2026-02-20T14:35:00Z"
    }
  }
}

Max attempts exceeded

After 3 failed attempts, the signer's OTP is locked. A new OTP must be sent:

Code
{
  "error": {
    "code": 429,
    "type": "OTP_LOCKED",
    "message": "Maximum OTP attempts reached. Request a new OTP.",
    "details": {
      "locked_until": "2026-02-20T14:40:00Z"
    }
  }
}

Proof certificate

After all signers complete, FairePlace generates a proof certificate — a JSON document that provides a legally admissible record of the signing process.

Retrieve the proof

Code
curl https://api.faireplace.com/api/leases/{lease_id}/signature/proof \
  -H "Authorization: Bearer $API_KEY"

Proof format

Code
{
  "status": "AVAILABLE",
  "proof": {
    "version": "1.0",
    "proof_id": "proof-550e8400-e29b-41d4-a716-446655440000",
    "generated_at": "2026-02-19T16:45:01Z",
    "document": {
      "document_signature_id": "550e8400-e29b-41d4-a716-446655440000",
      "lease_id": "550e8400-e29b-41d4-a716-446655440001",
      "original_document_hash": "a1b2c3d4e5f6789012345678abcdef0123456789abcdef0123456789abcdef01",
      "signed_document_hash": "f0e1d2c3b4a5968778695a4b3c2d1e0f...",
      "page_count": 12,
      "created_at": "2026-02-19T10:08:00Z",
      "completed_at": "2026-02-19T16:45:00Z"
    },
    "signers": [
      {
        "signer_type": "PROPRIETAIRE",
        "identity": {
          "email": "jean.dupont@sci-rivoli.com",
          "phone": "+33612345678",
          "first_name": "Jean",
          "last_name": "Dupont"
        },
        "process": {
          "notification_sent_at": "2026-02-19T14:28:00Z",
          "otp_sent_at": "2026-02-19T14:29:00Z",
          "otp_validated_at": "2026-02-19T14:29:50Z",
          "signature_completed_at": "2026-02-19T14:30:00Z",
          "ip_address": "92.184.xxx.xxx",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
          "country_code": "FR"
        },
        "cryptographic": {
          "signature_hash": "abc123def456...",
          "certificate_issuer": "Certinomis"
        }
      },
      {
        "signer_type": "LOCATAIRE",
        "identity": {
          "email": "marie.martin@email.com",
          "phone": "+33698765432",
          "first_name": "Marie",
          "last_name": "Martin"
        },
        "process": {
          "notification_sent_at": "2026-02-19T16:43:00Z",
          "otp_sent_at": "2026-02-19T16:44:00Z",
          "otp_validated_at": "2026-02-19T16:44:50Z",
          "signature_completed_at": "2026-02-19T16:45:00Z",
          "ip_address": "86.247.xxx.xxx",
          "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)...",
          "country_code": "FR"
        },
        "cryptographic": {
          "signature_hash": "def789ghi012...",
          "certificate_issuer": "Certinomis"
        }
      }
    ],
    "audit_trail": [
      {
        "timestamp": "2026-02-19T14:28:00Z",
        "event_type": "SignatureRequested",
        "actor_type": "PROPRIETAIRE",
        "description": "Signature request sent to owner"
      },
      {
        "timestamp": "2026-02-19T14:30:00Z",
        "event_type": "OtpValidated",
        "actor_type": "PROPRIETAIRE",
        "description": "OTP validated and signature completed"
      },
      {
        "timestamp": "2026-02-19T16:45:00Z",
        "event_type": "DocumentFinalized",
        "actor_type": "SYSTEM",
        "description": "All signatures collected, document finalized"
      }
    ],
    "compliance": {
      "eidas_level": "Advanced Electronic Signature",
      "signature_format": "PAdES-B",
      "etsi_standard": "ETSI EN 319 142-1",
      "hash_algorithm": "SHA-256",
      "retention_years": 10
    }
  },
  "pdf_url": "https://api.faireplace.com/api/media/serve/proof-pdf-id",
  "json_url": "https://api.faireplace.com/api/media/serve/proof-json-id"
}

Proof fields explained

Section	Purpose
document	SHA-256 hash of the original document — proves the signed document matches
signers	Audit trail for each signer: when OTP was sent, validated, and when they signed
certificate	Certificate authority details and eIDAS compliance level
integrity	Hash chain linking the document, signatures, and proof together

eIDAS compliance

FairePlace signatures meet the Advanced Electronic Signature (AdES) level under EU Regulation 910/2014 (eIDAS):

eIDAS Requirement	FairePlace Implementation
Uniquely linked to signer	OTP sent to signer's personal mobile phone
Identifies the signer	Identity verified via email + phone number
Under sole control of signer	OTP valid 5 minutes, 3 attempts max, single-use
Detects subsequent changes	PAdES-B with SHA-256 hash — any modification breaks the seal
Qualified certificate	Certinomis (ANSSI-qualified trust service provider)
Qualified timestamp	Certinomis TSA (RFC 3161 compliant)

Legal validity in France

Under French law (Article 1367 of the Civil Code), an electronic signature has the same legal force as a handwritten signature when it meets:

1. A reliable identification process
2. A link between the signature and the document

FairePlace's Advanced Electronic Signature satisfies both requirements through OTP verification and PAdES-B certificate embedding.

Troubleshooting

Signer didn't receive the SMS

1. Verify the phone number is in international format (e.g., +33612345678)
2. Check that the number is a mobile phone (landlines cannot receive SMS)
3. Wait 60 seconds and resend the OTP
4. If the issue persists, verify the signer's phone is not in "Do Not Disturb" mode

Signature expired

Signatures expire after 14 days by default. If expired:

1. Cancel the expired signature
2. Generate a new PDF (if lease data changed)
3. Initiate a new signature process

Proof not available

The proof certificate is only generated after all signers complete. Check GET /leases/{id}/signature/status to verify the overall status is Completed.

---

Related

• Electronic Signatures — Full signature workflow
• Lease Workflow — End-to-end tutorial
• Payments & Credits — Purchase signature credits