YCMT EU Partner Developer API Guide

Authentication API + Customer-Context Core API | v1.0

1. Purpose and reading rules

This guide is the main human-readable API reference for partner developers integrating a branded application with the YCMT EU customer-facing API surface. It explains what to call, when to call it, which headers to send, what key request and response fields mean, and how endpoints work together.

This document is intentionally partner-facing. It does not describe YCMT internal architecture or internal compliance decisioning. Partner applications call the documented API and display YCMT-provided statuses, instructions, and remediation signals to the customer.

1.1 Partner-safe integration principle

Your application presents the branded customer experience. YCMT validates the customer, partner, KYC, sanctions, transaction, and settlement controls before any regulated action proceeds. The partner application must not create shortcuts around registration, authentication, KYC, quote acceptance, transfer confirmation, funding, cancellation, or status tracking.

1.2 How to use this guide

1. Read the common request rules before implementing any endpoint.
2. Implement Authentication API endpoints first: registration, login, refresh, logout, password reset, and device registration.
3. Implement Customer-Context Core API endpoints next: profile, KYC, beneficiaries, quotes, disclosures, transfers, cancellation, and status polling.
4. Use the Flows Guide to validate end-to-end customer journeys.
5. Use the Errors, Statuses, and Retry Guide for edge cases and resilience.
6. Use the OpenAPI and Postman pack for machine-readable schemas and executable examples.

2. API families

2.1 Environment base URLs

The sandbox URL above is a placeholder format. YCMT onboarding will provide the actual URL and access credentials. Never mix sandbox and production credentials.

3. Common request rules

3.1 Required headers

3.2 Example unauthenticated request

POST /v1/auth/start HTTP/1.1

Host: sandbox.api.eu.yescash.example

Content-Type: application/json

Accept: application/json

X-Correlation-Id: 2c3eb391-57e1-4312-a59d-85f9df38cf62

Ocp-Apim-Subscription-Key: <sandbox-api-key>

{

"identifierType": "email",

"identifier": "alice.martinez@example.com"

}

3.3 Example authenticated request

GET /v1/core/profile HTTP/1.1

Host: sandbox.api.eu.yescash.example

Accept: application/json

Authorization: Bearer <customer-access-token>

X-Correlation-Id: 2c3eb391-57e1-4312-a59d-85f9df38cf62

Ocp-Apim-Subscription-Key: <sandbox-api-key>

3.4 Security rules for partner developers

• Do not log access tokens, refresh tokens, OTPs, passwords, private keys, device signing material, full identity documents, or full payment details.
• Store tokens only in secure platform storage appropriate to the channel and device type.
• Use TLS for all calls and reject invalid certificates.
• Use correlation IDs in logs so YCMT can investigate without exposing secrets.
• Show customer-facing remediation only from documented statuses, errors, and response fields.
• Do not infer internal reasons for KYC, sanctions, customer status, or transfer decisions.

4. Authentication API

The Authentication API is used before or alongside customer-context actions. It returns customer tokens, manages customer login identifiers, supports password reset, and registers the customer device used for higher-assurance transfer confirmation.

4.1 Authentication endpoint catalogue

4.2 Login

POST /v1/auth/start

Starts login using the customer identifier. The response returns a short-lived loginAttemptId used by /v1/auth/login.

{

"identifierType": "email",

"identifier": "alice.martinez@example.com"

}

POST /v1/auth/login

Completes login. Most successful responses return tokens and subscriptionId. Some responses may require MFA challenge or MFA enrolment; the partner app must follow the returned authStatus and next instructions.

Successful token response fields

4.3 Token refresh and logout

4.4 Customer registration

Registration is a three-step customer-facing flow: start, verify OTP, then set password. A successful final step returns tokens and the partner-facing subscriptionId.

4.5 Identifier management

Authenticated customers may list, add, and remove login identifiers. Identifier add and remove use two-step OTP flows. The partner app must present masked identifiers and avoid exposing full values except where the customer entered them.

4.6 Password reset

4.7 Device registration

Device registration prepares the customer device for high-assurance transfer confirmation. The partner app starts registration, generates or selects a customer-device signing key according to the Security and Signing Guide, and completes registration by submitting the public key and proof. Private key material must never leave the customer device.

5. Customer-Context Core API

Every Core API endpoint requires a customer access token in the Authorization header. The partner application must treat the token as the sole customer context for the request and must not place internal customer identifiers in URLs or request bodies.

5.1 Core endpoint catalogue

5.2 Profile

POST /v1/core/profile

Submits customer identity attributes required before KYC and money movement. The partner app should collect only the fields required by the current UI and corridor requirements, and submit them in the documented format.

GET /v1/core/profile

Reads the partner-visible customer state. This is the main endpoint for the partner app to decide which customer screen to show next.

5.3 KYC sessions and KYC webview

KYC capture is performed through a YCMT-served webview. The partner app opens the webviewUrl returned by /v1/core/kyc-sessions and polls the KYC session endpoint for state.

• Open the webviewUrl in the customer-facing app using the approved webview integration pattern.
• Do not intercept or modify documents, liveness capture, or verification data inside the webview.
• After the webview closes, poll the KYC session state and then refresh /v1/core/profile to show the correct next step.
• Use documented remediation messages only; do not infer internal KYC reasons.

5.4 Beneficiaries

Beneficiaries are customer-created recipients. A beneficiary may require screening before it can be used in a transfer.

5.5 Quotes and disclosure

The quote and disclosure sequence must be implemented carefully. The customer must see the required disclosure before quote acceptance. Expired quotes must not be accepted; the app should create or fetch a new quote as instructed by the error response.

Quote response fields to display

5.6 Transfers

Transfers proceed through quote acceptance, transfer submission, transfer confirmation, funding, and status tracking. The partner app must follow nextStep and transferStatus fields rather than assuming a fixed timing.

5.7 Funding webview

A successful transfer confirmation may return a fundingSession containing a fundingWebviewUrl. The partner app opens that URL for the customer. YCMT controls the funding flow. The partner app is a display host and must not collect or store payment credentials unless a separate written instruction explicitly allows it.

6. Statuses the partner app must handle

6.1 Customer statuses

6.2 Transfer handling principle

Always drive the UI from transferStatus, nextStep, customerActionExpected, confirmationChallenge fields, fundingSession fields, cancellation fields, and refund fields returned by the API. Do not hard-code transfer progress based only on elapsed time.

7. Common response and error model

Successful responses return the resource or action result described by the endpoint. Error responses use a structured error object. The partner app should map error codes to the documented handling rules in the Errors, Statuses, and Retry Guide.

7.1 Generic error response shape

{

"error": {

"code": "quote.expired",

"message": "The quote is no longer valid.",

"correlationId": "2c3eb391-57e1-4312-a59d-85f9df38cf62",

"hint": "hint.partner_app.refresh_quote",

"remediation": "remediation.customer_ux.review_new_quote"

}

}

7.2 Partner app error handling rules

• Do not display raw technical error details to customers unless the guide explicitly marks them customer-safe.
• Show the customer-safe remediation associated with the error category.
• For token expiry, refresh the token and retry where safe.
• For quote expiry, request a new quote and show the customer the new price/disclosure before acceptance.
• For validation errors, highlight the field or step the customer can correct.
• For customer.statusBlocking, show generic support guidance and do not disclose internal reasons.
• For rate limits or temporary unavailability, follow Retry-After if provided and avoid retry storms.

8. Idempotency, pagination, and retries

8.1 Idempotency

For write operations that create or change business state, use an Idempotency-Key generated per business action. Reuse the same key only when retrying the same action after timeout or network failure. Do not reuse one key for different customer actions.

8.2 Pagination

List endpoints may return nextCursor. When nextCursor is present, call the same list endpoint again with the cursor parameter. Do not construct or modify cursor values; treat them as opaque strings.

8.3 Safe retry rules

9. Minimal implementation checklist

10. What not to build

The partner application must not implement any workaround that bypasses YCMT controls or changes the regulatory responsibility split.

• Do not create or execute transfers outside the documented customer-context APIs.
• Do not treat partner backend credentials as authority to move customer money.
• Do not store or expose internal customer identifiers. Use subscriptionId only where the API returns it.
• Do not infer or disclose internal AML, KYC, sanctions, fraud, or customer-status reasons.
• Do not collect or store payment credentials outside the approved funding flow.
• Do not alter or suppress YCMT-required disclosures.
• Do not reuse one customer token for another customer or another partner channel.
• Do not hard-code assumptions about transfer timing, KYC outcomes, or cancellation outcomes.

11. Support and escalation

Appendix A. Endpoint summary by build order