YCMT-EU Developer Package — Quick Start

Version: v1.0 draft

API host: https://api.yes.cash

Audience: Partner technical teams building customer-facing integration apps.

---

1. What this package is

This package helps partner engineering teams integrate their web or mobile application with the YCMT-EU API.

It focuses on what developers need to build:

• customer registration and login;
• token refresh and logout;
• device registration;
• customer profile and KYC flow;
• beneficiary management;
• quote acceptance;
• transfer creation, confirmation, funding, cancellation, and status tracking;
• error handling, idempotency, correlation logging, and go-live readiness.

This package is intentionally technical and implementation-focused. It does not include internal operating procedures, internal approval logic, or non-developer material.

---

2. Before you start

You need the following from YCMT before integration:

Do not start production integration before quote signing, device registration, and transfer funding flows pass sandbox testing.

---

3. API host

Use this host for API calls:

https://api.yes.cash

Example endpoints:

POST https://api.yes.cash/v1/auth/start
POST https://api.yes.cash/v1/auth/login
GET  https://api.yes.cash/v1/core/profile
POST https://api.yes.cash/v1/core/quotes/{quoteId}/accept
GET  https://api.yes.cash/v1/core/transfers/{transferId}

---

4. Required headers

4.1 Common headers

Send these headers on API requests unless a specific endpoint says otherwise:

Content-Type: application/json
Accept: application/json
Ocp-Apim-Subscription-Key: <partner-api-subscription-key>
X-Correlation-Id: <uuid-v4>

4.2 Authenticated customer requests

For customer-authenticated endpoints, also send:

Authorization: Bearer <accessToken>

4.3 Idempotent write requests

For write operations that create or advance a business action, send:

Idempotency-Key: <uuid-v4>

Use a new idempotency key for each new business action. Reuse the same key only when retrying the same action after a timeout or network failure.

---

5. Authentication in 3 steps

Step 1 — Start login

POST /v1/auth/start

Purpose: start login using the customer identifier, such as email or phone.

Example:

POST https://api.yes.cash/v1/auth/start
Content-Type: application/json
Ocp-Apim-Subscription-Key: <partner-api-subscription-key>
X-Correlation-Id: 1c214b42-05e6-4b43-86e8-7298a24b50bc

{
  "identifier": "alice@example.com"
}

Step 2 — Complete login

POST /v1/auth/login

Purpose: submit the credential and receive tokens.

Successful response includes an accessToken, refreshToken, and subscriptionId.

The partner app must store tokens securely and must not use token claims for authorization decisions. Use the token only as the bearer credential for API calls.

Step 3 — Call Core API

Use the accessToken from login:

GET https://api.yes.cash/v1/core/profile
Authorization: Bearer <accessToken>
Ocp-Apim-Subscription-Key: <partner-api-subscription-key>
X-Correlation-Id: 79df65ef-a9dc-43a7-9dd5-c6ef416b9d5e

---

6. Customer registration flow

For a new customer, use this sequence:

POST /v1/auth/register/start
POST /v1/auth/register/verify-otp
POST /v1/auth/register/set-password
POST /v1/auth/device-registration/start
POST /v1/auth/device-registration/complete

After registration, direct the customer to complete profile and KYC steps before attempting a transfer.

---

7. Standard integration flow

A normal customer journey follows this sequence:

1. Register or login customer
2. Register customer device
3. Submit or read customer profile
4. Start KYC session if required
5. Add beneficiary
6. Create or retrieve quote
7. Show disclosure
8. Accept quote
9. Create transfer
10. Submit transfer
11. Confirm transfer if device confirmation is required
12. Open funding webview when returned
13. Poll transfer status
14. Show final status to customer

Core endpoints used in this journey:

GET  /v1/core/profile
POST /v1/core/profile
POST /v1/core/kyc-sessions
GET  /v1/core/kyc-sessions/{kycSessionId}
GET  /v1/core/beneficiaries
POST /v1/core/beneficiaries
GET  /v1/core/quotes/{quoteId}
GET  /v1/core/quotes/{quoteId}/disclosure
POST /v1/core/quotes/{quoteId}/accept
POST /v1/core/transfers
POST /v1/core/transfers/{transferId}/submit
POST /v1/core/transfers/{transferId}/confirm
GET  /v1/core/transfers/{transferId}
GET  /v1/core/transfers
POST /v1/core/transfers/{transferId}/cancel

---

8. Quote signing summary

Partner-issued quotes must be signed before YCMT can accept them.

Minimum technical requirements:

The partner is responsible for generating the signed quote payload and publishing the public key through its JWKS endpoint.

Full implementation details are in:

06_Quote_Signing_Guide.md
07_Partner_JWKS_Key_Management.md

---

9. Device-bound confirmation summary

The customer device must register a public key before transfer confirmation flows that require device-bound signing.

Minimum technical requirements:

Full implementation details are in:

08_Device_Bound_Authentication.md

---

10. Error handling basics

All integration code must handle:

• expired token;
• invalid token;
• validation errors;
• quote expired;
• duplicate idempotency key;
• resource not found;
• transfer state not allowing the requested action;
• temporary service unavailability.

Recommended handling pattern:

Detailed error behavior is in:

05_Headers_Idempotency_Errors.md

---

11. Customer status UX summary

Customer status affects what the partner app should allow the customer to do.

Do not infer internal reasons from status. Display only the customer-facing action required by the API response.

---

12. Files included in this package

00_README_Quick_Start.md
01_Integration_Overview.md
02_Authentication_Guide.md
03_Core_API_Guide.md
04_End_to_End_Flows.md
05_Headers_Idempotency_Errors.md
06_Quote_Signing_Guide.md
07_Partner_JWKS_Key_Management.md
08_Device_Bound_Authentication.md
09_Webviews_Guide.md
10_Customer_Status_and_UX_Guide.md
11_Sandbox_and_Testing_Guide.md
12_Go_Live_Checklist.md
CHANGELOG.md
api-reference/auth.openapi.yaml
api-reference/core.openapi.yaml
postman/YCMT_EU_API.postman_collection.json
postman/YCMT_EU_Sandbox.postman_environment.json

---

13. Sandbox certification path

Before go-live, the partner integration must pass sandbox certification.

Minimum certification checks:

• registration flow works;
• login and token refresh work;
• device registration works;
• profile and KYC flow works;
• beneficiary creation works;
• quote signing works;
• quote acceptance works;
• transfer submission works;
• transfer confirmation works where required;
• funding webview opens and returns correctly;
• transfer status polling works;
• cancellation flow works where allowed;
• error handling works;
• idempotent retries work;
• correlation IDs are logged by the partner application.

Use:

11_Sandbox_and_Testing_Guide.md
12_Go_Live_Checklist.md

---

14. Support information

For integration support, use the technical onboarding channel provided by YCMT.

When raising an issue, include:

• environment: sandbox or production;
• endpoint;
• timestamp;
• X-Correlation-Id;
• idempotency key, if used;
• sanitized request body;
• sanitized response body;
• observed vs expected behavior.

Never send customer passwords, refresh tokens, private keys, or full payment instrument details in support tickets.