EpitaCard API (2026-08-01)

Amounts are always integers. There is no decimal, no second currency, and no way to move this account to live mode.

Your team owns one merchant and two keys.

The secret key is accepted two ways. As a bearer token:

Authorization: Bearer sk_test_tNN_…

Or as HTTP Basic, with the secret key as the username and an empty password — which is what most clients produce from a user: credential pair:

Authorization: Basic <base64("sk_test_tNN_…:")>

A secret key is shown once, when it is issued and when it is rotated, and is stored only as a hash afterwards. Nobody can recover it for you; rotate to get a new one, which invalidates the old one immediately.

The merchant dashboard signs in with a browser session cookie. That session is not an API credential and cannot create or confirm a payment. If a session cookie rides along with an Authorization header the header wins, and a header and cookie belonging to different merchants are rejected with 401 credential_conflict.

A payment intent starts at requires_payment_method.

Confirming an intent writes processing before it attempts any terminal status, then resolves to one. Whether a concurrent read sees that marker while the call is still running depends on Idempotency-Key: without the header the intent is readable at processing straight away; with it the intent keeps the state it had — or does not exist yet, when the create is what is being confirmed — until the call returns. Either way a client timeout never means the payment did not happen — re-read the intent. Confirming an intent that already left requires_payment_method returns 400 invalid_request.

There is no cancellation and no refund. A payment that must not stand is a business problem on your side, not an API call.

Pass one of these tokens as payment_method. Any other card number is rejected with 400 invalid_request.

Only processing_error, rate_limited, api_error and service_unavailable are worth retrying. Retrying a terminal code produces the same answer.

Retry with the same order_id. That is what stops a retry from charging your buyer twice.

Two independent protections.

1. Idempotency-Key header. Supported on:

• POST /v1/payment_intents
• POST /v1/payment_intents/{id}/confirm

A repeat of the same request with the same key replays the stored response and adds Idempotent-Replayed: true. Requests are matched on method, request_path, canonical_body, so the same key sent with a different body, or against a different PaymentIntent, returns 409 idempotency_error. A stored response is kept only for status 200, 201, 402, 409; status 400, 404, 500 does not consume the key, so a retry gets a fresh attempt. An absent body and {} are the same request.

GET requests ignore the header. These routes reject it with 400:

• POST /v1/webhook_endpoints
• PATCH /v1/webhook_endpoints/{id}
• POST /v1/api_keys/rotate

2. (merchant, order_id) uniqueness. This one needs no header, which makes it the protection that covers a retry after a network timeout. Re-creating an intent for an order_id you already used returns the existing intent with 200 when the amount matches, and 409 order_amount_mismatch when it does not.

payment_intents, events, webhook_endpoints, webhook_deliveries are ordered by created DESC then id DESC. Pass the last ID you received as starting_after to get the next page; the server selects rows where created < cursor.created OR (created = cursor.created AND id < cursor.id). Every list response carries has_more and next_starting_after.

Register an HTTPS endpoint you control with POST /v1/webhook_endpoints and keep the whsec_… signing secret it returns. There are exactly 3 event types:

• payment_intent.succeeded
• payment_intent.failed
• payment_intent.processing

Delivery is at least once with bounded retries, so de-duplicate on event.id. Delivery never changes or delays the synchronous API response you already got.

Every delivery carries an EpitaCard-Signature header:

EpitaCard-Signature: t=1786900201,v1=0000000000000000000000000000000000000000000000000000000000000000

t=<unix>,v1=<hex hmac_sha256(secret, timestamp + "." + raw_body)>. Reject timestamps outside a five-minute window and compare decoded MAC bytes in constant time.

Read the raw body before decoding it — re-serialised JSON does not produce the same MAC:

func verifyEpitaCardSignature(secret, header string, body []byte, now time.Time) error {
    var timestampText, signatureHex string
    for _, part := range strings.Split(header, ",") {
        key, value, ok := strings.Cut(strings.TrimSpace(part), "=")
        if !ok {
            continue
        }
        switch key {
        case "t":
            timestampText = value
        case "v1":
            signatureHex = value
        }
    }
    timestamp, err := strconv.ParseInt(timestampText, 10, 64)
    if err != nil {
        return fmt.Errorf("invalid signature timestamp: %w", err)
    }
    delta := now.Unix() - timestamp
    if delta < -300 || delta > 300 {
        return errors.New("signature timestamp outside five-minute window")
    }
    received, err := hex.DecodeString(signatureHex)
    if err != nil {
        return fmt.Errorf("invalid v1 signature: %w", err)
    }
    mac := hmac.New(sha256.New, []byte(secret))
    _, _ = io.WriteString(mac, timestampText+".")
    _, _ = mac.Write(body)
    if !hmac.Equal(received, mac.Sum(nil)) {
        return errors.New("signature mismatch")
    }
    return nil
}

hmac.Equal is the constant-time comparison; == on the hex strings leaks timing. Verify before unmarshalling and before any side effect.

Create, confirm, retrieve, and search payment attempts.

Read total settled revenue.

Read immutable merchant event history.

Register and inspect signed event destinations.

Inspect key metadata and rotate the active secret key.

Authenticate merchants and read the owner-scoped request log.

Public destination-country VAT rates.