curl https://sandbox.api.bovillus.finance/v3/oauth2/token \
  --cert client.crt --key client.key \
  -d grant_type=client_credentials \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion="$ASSERTION" \
  -d scope="payments:read confirmations:write"

# 200
{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 300,
  "scope": "payments:read confirmations:write" }

import fs from "node:fs";
import https from "node:https";
import { SignJWT, importPKCS8 } from "jose";

const TOKEN_URL = "https://sandbox.api.bovillus.finance/v3/oauth2/token";
const key = fs.readFileSync("client.key");                 // PKCS#8 PEM
const agent = new https.Agent({ cert: fs.readFileSync("client.crt"), key });

const assertion = await new SignJWT({})
  .setProtectedHeader({ alg: "ES256", kid: process.env.KEY_ID })
  .setIssuer(process.env.CLIENT_ID).setSubject(process.env.CLIENT_ID)
  .setAudience(TOKEN_URL).setJti(crypto.randomUUID())
  .setIssuedAt().setExpirationTime("60s")
  .sign(await importPKCS8(key.toString(), "ES256"));

const body = new URLSearchParams({
  grant_type: "client_credentials",
  client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  client_assertion: assertion,
  scope: "payments:read confirmations:write",
});
// use the same agent (same certificate) for every call with this token

import time, uuid, jwt, requests

TOKEN_URL = "https://sandbox.api.bovillus.finance/v3/oauth2/token"
CERT = ("client.crt", "client.key")
key = open("client.key").read()

assertion = jwt.encode(
    {"iss": CLIENT_ID, "sub": CLIENT_ID, "aud": TOKEN_URL,
     "jti": str(uuid.uuid4()), "iat": int(time.time()), "exp": int(time.time()) + 60},
    key, algorithm="ES256", headers={"kid": KEY_ID})

r = requests.post(TOKEN_URL, cert=CERT, data={
    "grant_type": "client_credentials",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": assertion,
    "scope": "payments:read confirmations:write"})
token = r.json()["access_token"]   # bound to client.crt, valid 300 s

"@method": POST
"@target-uri": https://sandbox.api.bovillus.finance/v3/payments/2b8f4c1a-…/receiver-confirmations
"content-digest": sha-256=:9Xq2…=:
"idempotency-key": skit-conf-0001-acsc
"x-request-id": 6f1c2d1e-8a1b-4b7e-9f0e-2b6f5c1d9a10
"@signature-params": ("@method" "@target-uri" "content-digest" "idempotency-key" "x-request-id");created=1794400000;keyid="partner-skit-2026-11";alg="ecdsa-p256-sha256"

import { createHash, createPrivateKey, sign } from "node:crypto";

export function signedHeaders({ method, url, body, idemKey, requestId, keyId, pem }) {
  const digest = "sha-256=:" + createHash("sha256").update(body).digest("base64") + ":";
  const created = Math.floor(Date.now() / 1000);
  const params = `("@method" "@target-uri" "content-digest" "idempotency-key" "x-request-id")` +
                 `;created=${created};keyid="${keyId}";alg="ecdsa-p256-sha256"`;
  const base = [
    `"@method": ${method}`, `"@target-uri": ${url}`, `"content-digest": ${digest}`,
    `"idempotency-key": ${idemKey}`, `"x-request-id": ${requestId}`,
    `"@signature-params": ${params}`].join("\n");
  const sig = sign("sha256", Buffer.from(base),
                   { key: createPrivateKey(pem), dsaEncoding: "ieee-p1363" }).toString("base64");
  return { "Content-Digest": digest, "Idempotency-Key": idemKey, "X-Request-ID": requestId,
           "Signature-Input": `sig1=${params}`, "Signature": `sig1=:${sig}:` };
}

import base64, hashlib, time
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature

def signed_headers(method, url, body: bytes, idem_key, request_id, key_id, pem: bytes):
    digest = "sha-256=:" + base64.b64encode(hashlib.sha256(body).digest()).decode() + ":"
    params = ('("@method" "@target-uri" "content-digest" "idempotency-key" "x-request-id")'
              f';created={int(time.time())};keyid="{key_id}";alg="ecdsa-p256-sha256"')
    base = "\n".join([f'"@method": {method}', f'"@target-uri": {url}',
                      f'"content-digest": {digest}', f'"idempotency-key": {idem_key}',
                      f'"x-request-id": {request_id}', f'"@signature-params": {params}'])
    key = serialization.load_pem_private_key(pem, password=None)
    r, s = decode_dss_signature(key.sign(base.encode(), ec.ECDSA(hashes.SHA256())))
    sig = base64.b64encode(r.to_bytes(32, "big") + s.to_bytes(32, "big")).decode()
    return {"Content-Digest": digest, "Idempotency-Key": idem_key, "X-Request-ID": request_id,
            "Signature-Input": f"sig1={params}", "Signature": f"sig1=:{sig}:"}

POST /v3/payments/2b8f4c1a-6d3e-4f7a-9c2b-1e5d8a7f3c90/receiver-confirmations
Authorization: Bearer eyJ…
Content-Type: application/json
…signed headers from step 2…

{
  "result": "ACSC",
  "receiverReference": "SKIT-CR-889102",
  "settledAmount": { "currency": "USD", "value": "1000.00" },
  "valueDate": "2026-11-12",
  "confirmedAt": "2026-11-12T08:15:00Z"
}

# 201 → payment.status "ACSC", bovillusState "SETTLED_BY_RECEIVER", fee.chargedAt set

POST /bovillus/payments HTTP/1.1
Host: api.yourbank.example
Content-Type: application/json
Idempotency-Key: BOV-20261111-000123
X-Request-ID: 0d6e2c4a-9b1f-4f3e-8a7c-5e2d1b9f6a40
Content-Digest: sha-256=:…=:
Signature-Input: sig1=("@method" "@target-uri" "content-digest" "idempotency-key" "x-request-id");created=1794400000;keyid="bovillus-2026-11";alg="ecdsa-p256-sha256"
Signature: sig1=:…:

{
  "instructionId": "BOV-20261111-000123",
  "endToEndId": "SKIT-RED-0001",
  "uetr": "8a4d2f6e-3b1c-4e9a-8f7d-2c5b1a9e6d30",
  "paymentId": "2b8f4c1a-6d3e-4f7a-9c2b-1e5d8a7f3c90",
  "amount": { "currency": "USD", "value": "1000.00" },
  "debtor": { "name": "Bovillus Finance" },
  "debtorAccount": { "accountNumber": "08122800051" },
  "creditor": { "name": "SK Information Technologies" },
  "creditorAccount": { "otherId": "SKIT-CIS-20260827" },
  "purposeCode": "SUPP",
  "remittanceInformation": "Redemption lot 1",
  "confirmationUrl": "https://api.bovillus.finance/v3/payments/2b8f4c1a-…/receiver-confirmations",
  "createdAt": "2026-11-11T09:30:00Z"
}

HTTP/1.1 202 Accepted
Content-Type: application/json

{ "receiverReference": "SKIT-IN-55120", "status": "ACSP" }

{
  "eventId": "c1f7a0e2-5b3d-4c8e-9a6f-0d2b7e4c1a95",
  "type": "payment.settled",
  "occurredAt": "2026-11-12T08:15:03Z",
  "data": { "paymentId": "2b8f4c1a-…", "status": "ACSC", "bovillusState": "SETTLED_BY_RECEIVER", … }
}

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{ "type": "https://bovillus.finance/developers/errors/IDEMPOTENCY_CONFLICT",
  "title": "The Idempotency-Key was used with a different body",
  "status": 409, "code": "IDEMPOTENCY_CONFLICT",
  "requestId": "6f1c2d1e-8a1b-4b7e-9f0e-2b6f5c1d9a10", "retryable": false }