Documentationv3.2.0

Onboarding - KYC

SettleRamp supports partner-driven onboarding for compliance (KYC/AML). The onboarding flow can be embedded in the partner UX and is fully asynchronous -- status updates are delivered via callbacks and can also be polled.

Tip: Always include a callbackUrl when submitting KYC data. This lets SettleRamp push status updates to your system in real time instead of requiring you to poll.

High-level Flow

The onboarding process follows five steps. Each step maps to one or more API endpoints.

Retrieve Terms & Conditions

Fetch the latest T&C content so the customer can review and accept before proceeding.

Submit KYC profile

Send personal data, address, and sworn declarations (DDJJ). Include a callbackUrl for async status updates.

Complete 2FA (if required)

Some flows require an extra verification step. Send a code to the customer and verify it.

Upload documents

Upload identity images (ID front, ID back, selfie) as multipart/form-data.

Track KYC status

Poll the status endpoint or listen for webhook callbacks to track verification progress.

Retrieve Terms & Conditions

Fetch the latest terms and conditions content before starting the KYC flow. The customer must review and accept these terms.

GET{{apiUrl}}/api/partner/kyc/terms

Headers

Authorization: Bearer {{_affiliate_api_token}}

Submit KYC Profile

Creates or updates a KYC record for a customer. The partner provides a callbackUrl for async status updates. All personal data, address, and sworn declarations (DDJJ) are submitted in a single request.

POST{{apiUrl}}/api/partner/kyc

Headers

Authorization: Bearer {{_affiliate_api_token}}

Request Body Fields

personalData (object: name, lastname, gender, born, nationalId, taxId, occupation, occupationCategory, address), contactData (object: email, phone), isPEP, isOS, serviceAgreementCheck, statusCallbackUrl

Two-Factor Authentication (2FA)

Some onboarding flows require an extra verification step. The 2FA process uses a unique identifier ({{_2faId}}) and follows two steps: send codes, then verify.

Send Codes

Triggers a verification code to be sent to the customer via the specified channel (e.g. email).

POST{{apiUrl}}/api/users/2fa/{{_2faId}}/send-codes

Headers

Authorization: Bearer {{_affiliate_api_token}}

Body

methods: array of delivery methods (e.g. "phone", "email", "regEmail"), kycId: the KYC ID returned from the submit step

Verify Code

Submit the code the customer received to complete the 2FA step.

POST{{apiUrl}}/api/users/2fa/{{_2faId}}/verify-code

Headers

Authorization: Bearer {{_affiliate_api_token}}

Body

code: the verification code received by the customer

Upload Documents

Upload identity documents as multipart/form-data. This endpoint is called once per document type (idFront, idBack, selfie). Uses the KYC id ({{_kycId}}) returned from the profile submission. The Content-Type multipart boundary is set automatically by the client when using form-data.

POST{{apiUrl}}/api/partner/kyc/{{_kycId}}/files

Headers

Authorization: Bearer {{_affiliate_api_token}}Content-Type: multipart/form-data

Form-data Fields