OLW Fiat→Crypto Gateway API (v2)

Initiate a fiat card deposit that settles in cryptocurrency via a secure, hosted payment page.

OAuth 2.1 / API Key mTLS Option Signed Webhooks RFC 7807 errors Idempotency Rate Limits

Authentication

Preferred: OAuth 2.1 client-credentials with JWT access tokens (15m lifetime) and optional mTLS. Legacy API keys are supported during migration only.

# OAuth 2.1 client credentials
token_endpoint: POST /oauth2/token
scopes: gateway:create gateway:read

# API Key (legacy)
Authorization: Bearer <YOUR_API_KEY>

• Requests must originate from allow‑listed IPs or via mTLS.
• Rotate keys/tokens frequently; never log secrets.

Create Transaction

Create a transaction and obtain the hosted payment URL.

POST /v2/card_process
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <uuid>
X-Request-Id: <uuid>

{
  "amount": "74.00",
  "currencyCode": "EUR",
  "country": "MT",
  "dateOfBirth": "1959-04-28",
  "fullName": "Samy El Saghir",
  "merchantRef": "c233b19e-38e2-4894-test-138e531ftest",
  "userRef": "20231113153253-25795",
  "transactionRef": "20231113153253-25795",
  "email": "user@example.com",
  "phoneCode": "+356",
  "phoneNumber": "99127286"
}

Hosted Redirect

Redirect the customer to the provided url. Handles card entry, 3DS, and settlement. Use 302/303 redirects; avoid iframes.

Webhooks

POST /trans_result
X-OLW-Event: gateway.authorization
X-OLW-Delivery: evt_89k0w1
X-OLW-Timestamp: 1735668000
X-OLW-Signature: sha256=1e5c7f...

{"merchantRef":"c233b19e-...","transactionRef":"2023090514...","amount":"74.00","outcome":"OK","reason":"Authorized"}

• Verify X-OLW-Signature (HMAC-SHA256 with kid header).
• Reject if timestamp skew > 300s or delivery id replayed.
• Retry schedule: 0s, 30s, 2m, 10m, 1h (max 15 attempts).

Verification

Use POST /v2/verify with merchantRef and transactionRef to trigger a webhook resend.

Error Model (RFC 7807)

{
  "type": "https://docs.onelinkwallet.com/errors/validation",
  "title": "Invalid request",
  "status": 400,
  "detail": "currencyCode must be ISO 4217",
  "instance": "req_01HW...Q2"
}

Rate Limits & Idempotency

All POSTs require Idempotency-Key (UUIDv4/256‑bit). We publish RFC 9331 headers.

Idempotency-Key: 8c9f2c18-5c3a-4b0f-9db7-8a4f7e4a7332
RateLimit-Limit: 100
RateLimit-Remaining: 72
RateLimit-Reset: 30

Observability

• Send X-Request-Id with every call; echoed in responses and webhooks.
• Supports W3C Trace Context (traceparent).
• Logs are structured JSON; audit trails stored tamper‑evidently.

Code Examples

Node (fetch)

import fetch from "node-fetch";
const BASE = "https://secure.onelinkwallet.com/v2";
async function createGatewayTx(token){
  const res = await fetch(BASE+"/card_process",{
    method:"POST",
    headers:{"Authorization":"Bearer "+token,"Content-Type":"application/json","Idempotency-Key":crypto.randomUUID(),"X-Request-Id":crypto.randomUUID()},
    body:JSON.stringify({amount:"74.00",currencyCode:"EUR",country:"MT",dateOfBirth:"1959-04-28",fullName:"Samy El Saghir",merchantRef:"c233b...test",transactionRef:"20231113153253-25795"})
  });
  if(!res.ok) throw new Error(await res.text());
  return res.json();
}

Environments

Compliance & Standards

• Protocols: TLS 1.3 preferred (TLS 1.2 allowed with AEAD ciphers). HSTS enabled.
• Data: ISO 4217 (currency), ISO 3166-1 (country), RFC 3339 (dates/times).
• Errors: RFC 7807 Problem+JSON.
• Limits: RFC 9331 RateLimit headers.
• Security: OWASP API Top 10 mitigations (auth, injection, mass assignment, SSRF, etc.).
• Compliance: GDPR/UK GDPR, KSA PDPL; DPA and SCCs/IDTA available. PCI DSS SAQ-A (hosted card entry only).
• Crypto: FIPS 140-3 validated modules; secrets in managed KMS/HSM.