Onboard Existing End User to Another Bank

PATCH /v1/end-users//onboard — Starts onboarding an already-created end user with a new bank partner. Idempotent if already onboarded.

Initiates a new bank onboarding process for an end user who already exists on the Diameter platform. Use this endpoint when you want to expand an end user’s banking access to a partner that was not included in the original onboardInBanks array at creation time. The operation is idempotent — if an onboarding process for the given bank partner is already in progress or has completed, the endpoint returns the existing process state instead of creating a duplicate.

​

Endpoint

PATCH /v1/end-users/{id}/onboard

Required scope: com.diameterpay.api/end-users.write

​

Request Headers

Authorization · string · required

Bearer token obtained from your OAuth 2.0 token endpoint. Format: Bearer {access_token}

x-idempotency-key · string · required

A UUID v4 string you generate for each unique request. Ensures safe retries in case of network failures without starting duplicate onboarding processes.

​

Path Parameters

id · string · required

UUID v4 of the existing end user (individual or organization) to onboard with an additional bank partner.

​

Request Body

bankPartner · string · required

The bank partner to initiate onboarding with. One of: PORTAGE, SLOVAK_SAVINGS_BANK.

​

Response

Returns 200 OK with an onboarding process object describing the current or newly created state.

status · string

Outcome of the request. One of:

• CREATED — a new onboarding process was started.
• EXISTING_PROCESS_FOUND — an onboarding process for this end user and bank partner was already in progress; no new process was created.
• ALREADY_ONBOARDED — the end user has already completed onboarding with this bank partner; no new process was created.

onboardingProcessId · string

UUID v4 of the onboarding process (new or existing).

bankPartner · string

The bank partner this onboarding process is associated with.

processState · string

Current state of the onboarding process (e.g. PENDING, IN_REVIEW, APPROVED, REJECTED, COMPLETED).

endUserId · string

UUID v4 of the end user being onboarded.

message · string

Human-readable description of the outcome, useful for logging and debugging. For example: "Onboarding process created successfully." or "End user is already onboarded with this bank partner.".

This endpoint is fully idempotent. Sending the same bankPartner for an end user who is already onboarded will return ALREADY_ONBOARDED with the existing process details and will not create a new onboarding process or generate any side effects.

​

Example Request

curl --request PATCH \
  --url https://api.sandbox.diameterpay.com/v1/end-users/f47ac10b-58cc-4372-a567-0e02b2c3d479/onboard \
  --header 'Authorization: Bearer {access_token}' \
  --header 'x-idempotency-key: e3d4c5b6-a7f8-9012-bcde-f01234567890' \
  --header 'Content-Type: application/json' \
  --data '{
    "bankPartner": "SLOVAK_SAVINGS_BANK"
  }'

​

Example Responses

​

New onboarding process created

{
  "status": "CREATED",
  "onboardingProcessId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "bankPartner": "SLOVAK_SAVINGS_BANK",
  "processState": "PENDING",
  "endUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "message": "Onboarding process created successfully."
}

​

Onboarding already in progress

{
  "status": "EXISTING_PROCESS_FOUND",
  "onboardingProcessId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "bankPartner": "SLOVAK_SAVINGS_BANK",
  "processState": "IN_REVIEW",
  "endUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "message": "An onboarding process for this bank partner is already in progress."
}

​

End user already onboarded

{
  "status": "ALREADY_ONBOARDED",
  "onboardingProcessId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "bankPartner": "SLOVAK_SAVINGS_BANK",
  "processState": "COMPLETED",
  "endUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "message": "End user is already onboarded with this bank partner."
}