Getting Started

What Oceafin Provides

Before integration begins, Oceafin provides:

baseUrl: sandbox or production API base URL.

clientId: Partner API client identifier.

clientSecret: one-time secret used for HMAC request signatures.

Enabled scopes: route groups the client can call.

Enabled products: product workflows the partner can use.

Optional webhook URL registration and webhook signing secret.

Keep clientSecret and webhook secrets in a secret manager. Do not put them in
frontend code, mobile apps, source control, logs, tickets, or screenshots.

What The Partner Provides

The partner provides:

A stable partnerCustomerRef for each end user.

End-user consent evidence.

KYC or KYB evidence collected in the partner product.

Supporting documents uploaded or linked through the file endpoint.

Operation authorization evidence for money-out, refund, and conversion actions.

A public HTTPS webhook endpoint when webhook delivery is enabled.

Recommended Sandbox Sequence

Confirm the API base URL and credentials with Oceafin.

Implement request signing exactly as described in Authentication.

Send POST /partner/v1/customers for a test customer.

Upload or link onboarding files for that customer.

Submit KYC or KYB evidence.

Verify customer status transitions and webhook delivery.

Exercise only the product workflows enabled for the sandbox client.

Review request ids and error codes with Oceafin support if any scenario fails.

Environment Variables For Local Testing

These names are used by Oceafin's sample scripts and can also be used by a
partner-side test harness:

OCEAFIN_PARTNER_API_BASE_URL=https://api.oceafin.com
OCEAFIN_PARTNER_API_CLIENT_ID=<client-id>
OCEAFIN_PARTNER_API_CLIENT_SECRET=<client-secret>
OCEAFIN_PARTNER_API_WEBHOOK_SECRET=<webhook-secret>

Request Checklist

Every request must have:

X-Partner-Client-Id

X-Partner-Timestamp

X-Partner-Nonce

X-Partner-Signature

X-Request-Id

Every non-GET request must also have:

Idempotency-Key

Integration Checklist

Customer creation works with a stable partnerCustomerRef.

Repeating the same mutation with the same Idempotency-Key returns the stored
response.

Reusing an Idempotency-Key with a different body returns an idempotency
conflict.

KYC and KYB submissions use fileAssetId values from the Partner file endpoint.

Product calls are scoped to Oceafin customerId values returned by the Partner
API.

Money-out, refund, and conversion calls include operation authorization
evidence.

Webhook signature verification is implemented before acting on webhook data.

Getting Started

What Oceafin Provides#

What The Partner Provides#

Recommended Sandbox Sequence#

Environment Variables For Local Testing#