Oceafin Partner API V1

This guide is for partners integrating directly with the Oceafin Partner API.
The formal API contract is openapi/partner-api.yaml; this documentation explains
the integration model, request signing, common workflows, webhooks, and error
handling expected from a partner implementation.

Base URLs

Environment	Base URL
Production	`https://api.oceafin.com`
Sandbox	Provided by the Oceafin onboarding team

All Partner API paths are under /partner/v1.

Document Structure

Document	Purpose
Getting Started	Provisioning inputs, first request, and integration checklist.
Authentication	Required headers, HMAC signature, nonce, timestamp, and idempotency rules.
Customers And Onboarding	Customer creation, file upload/linking, KYC, KYB, and customer statuses.
Product Workflows	Fiat, crypto, collection, refund, conversion, balance, and transaction flows.
Webhooks	Event payload shape, signature verification, delivery, and retries.
Errors	Partner problem response format, common error codes, and retry guidance.

Integration Model

A Partner is the external platform using Oceafin services for its own end users.
Each partner is isolated by an Oceafin Partner Tenant. The partner does not pass
Oceafin tenant ids, business ids, merchant ids, or internal processing
identifiers to the API.

A Customer is the partner's end user in Oceafin. The partner creates a Customer,
submits KYC or KYB evidence for that Customer, and then uses enabled product
workflows for that Customer.

After approval, Oceafin assigns and manages the internal processing identifiers
needed to operate the enabled products. Partners must not send internal
processing identifiers in customer creation or onboarding requests.

Partner Responsibilities

Partners own:

End-user UI and consent capture.

KYC or KYB data collection.

Supporting document collection.

Partner-side user authentication and operation approvals.

Request signing, nonce uniqueness, timestamp freshness, and idempotency keys.

Webhook endpoint availability and webhook signature verification.

Oceafin owns:

API client provisioning.

Product and scope enablement.

Customer and product resource ownership checks.

Server-side onboarding submission and processing.

Product validation, limits, fees, status mapping, ledger posting, and webhooks.

First Successful Request

After receiving a sandbox clientId and one-time clientSecret, create a test
Customer:

Expected success response:

{
  "customerId": "00000000-0000-0000-0000-000000000000",
  "partnerCustomerRef": "cust-100001",
  "customerType": "INDIVIDUAL",
  "status": "DRAFT",
  "createdAt": "2026-06-28T00:00:00Z",
  "updatedAt": "2026-06-28T00:00:00Z"
}

See Authentication before sending real requests.

Oceafin Partner API V1

Base URLs#

Document Structure#

Integration Model#

Partner Responsibilities#

First Successful Request#

Base URLs

Document Structure

Integration Model

Partner Responsibilities

First Successful Request