Guide

Integration Overview

Understand the customer app integration model and API surfaces.

YCMT-EU Developer Package — Integration Overview

Version: v1.0 draft

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

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

---

1. Purpose

This document explains how a partner application integrates with the YCMT-EU API at a high level.

It is intended for engineers who need to understand:

which API surfaces are used;
how the customer app authenticates;
how Auth API and Core API work together;
which actions the partner app performs;
which actions are handled by YCMT;
how a normal remittance journey flows end to end.

This document is implementation-focused. It does not include internal YCMT operating procedures, internal decision logic, or non-developer material.

---

2. Integration model

The partner builds and operates the customer-facing web or mobile application.

The partner app:

presents the customer experience;
collects customer input;
calls the YCMT API;
securely stores customer tokens on the customer device where applicable;
handles redirects and webview return flows;
displays API responses and customer-facing next steps;
logs correlation IDs for support and troubleshooting.

The YCMT API:

authenticates customers;
issues and refreshes tokens;
manages customer profile and KYC flow;
validates and accepts quotes;
manages beneficiaries;
creates, submits, confirms, funds, cancels, and tracks transfers;
returns customer-facing status and remediation information.

High-level flow:

Partner Customer App
  -> https://api.yes.cash
  -> YCMT Auth API / YCMT Core API
  -> YCMT processing platform
  -> API response to Partner Customer App

---

3. API surfaces

The YCMT-EU customer integration uses two API surfaces.

API	Base path	Purpose
Auth API	`/v1/auth`	Customer registration, login, token refresh, logout, identifiers, password reset, and device registration.
Core API	`/v1/core`	Profile, KYC, beneficiaries, quotes, transfers, funding, cancellation, and transfer status.

Example URLs:

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

---

4. Customer-authenticated model

Most integration actions are performed in the context of an authenticated customer.

The standard pattern is:

1. Customer logs in or registers through the partner app.
2. Partner app receives YCMT-issued access and refresh tokens.
3. Partner app calls Core API using Authorization: Bearer <accessToken>.
4. YCMT resolves the customer and partner context server-side.
5. YCMT returns only the data and actions available for that customer session.

The partner app must not use token claims to make authorization decisions. Treat the token as a bearer credential and pass it to the API.

---

5. Required request headers

Most API calls use the following headers:

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

Customer-authenticated Core API calls also use:

Authorization: Bearer <accessToken>

Write operations that create or advance a business action may also require:

Idempotency-Key: <uuid-v4>

Use a new X-Correlation-Id per request or per customer journey, depending on your logging model. Use the same Idempotency-Key only when retrying the same business action.

---

6. Standard customer journey

A normal integration journey follows this sequence:

1. Register or log in customer
2. Register customer device
3. Submit or read customer profile
4. Start KYC session if required
5. Add beneficiary
6. Retrieve quote
7. Show disclosure
8. Accept quote
9. Submit transfer
10. Confirm transfer if required
11. Open funding webview if returned
12. Poll transfer status
13. Show final result to customer

The partner app should treat the API response as the source of truth for the next customer action.

---

7. Authentication flow summary

New customer

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, the customer should complete profile and KYC before attempting a transfer.

Returning customer

POST /v1/auth/start
POST /v1/auth/login

If the access token expires:

POST /v1/auth/refresh

When the customer logs out:

POST /v1/auth/logout

---

8. Core API flow summary

Profile and KYC

GET  /v1/core/profile
POST /v1/core/profile
POST /v1/core/kyc-sessions
GET  /v1/core/kyc-sessions/{kycSessionId}

Use these endpoints to collect and check customer onboarding status.

Beneficiaries

GET  /v1/core/beneficiaries
POST /v1/core/beneficiaries
GET  /v1/core/beneficiaries/{beneficiaryId}
POST /v1/core/beneficiaries/{beneficiaryId}/archive

Use these endpoints to manage recipients available to the authenticated customer.

Quotes and disclosure

GET  /v1/core/quotes/{quoteId}
GET  /v1/core/quotes/{quoteId}/disclosure
POST /v1/core/quotes/{quoteId}/accept

The partner is responsible for generating and signing the quote payload according to the quote signing guide.

Transfers

POST /v1/core/transfers/{transferId}/submit
POST /v1/core/transfers/{transferId}/confirm
POST /v1/core/transfers/{transferId}/cancel
GET  /v1/core/transfers/{transferId}
GET  /v1/core/transfers

Use the transfer detail and list endpoints to keep the customer UI synchronized with the latest transfer state.

---

9. Quote signing responsibility

Partner-issued quotes must be signed before acceptance.

Minimum requirements:

Item	Requirement
Signature format	JWS
Algorithm	RS256
Minimum RSA key size	RSA-2048
Recommended RSA key size	RSA-3072
Canonicalisation	JCS
Public key discovery	Partner-published JWKS URL

Implementation details are provided in:

06_Quote_Signing_Guide.md
07_Partner_JWKS_Key_Management.md

---

10. Device-bound authentication responsibility

The partner app must support customer device registration and device-bound confirmation.

The customer device:

generates the device signing key;
stores the private key securely;
submits the public key during registration;
signs device confirmation assertions when required.

Relevant endpoints:

POST /v1/auth/device-registration/start
POST /v1/auth/device-registration/complete
POST /v1/core/transfers/{transferId}/confirm

Implementation details are provided in:

08_Device_Bound_Authentication.md

---

11. Webview responsibility

Some flows may return a YCMT-hosted webview URL.

Common webview cases:

KYC capture;
funding.

The partner app is responsible for:

opening the webview URL;
preserving the customer session context;
handling close, success, cancellation, and timeout outcomes;
returning the customer to the correct app screen;
polling the relevant API endpoint after the webview closes.

Implementation details are provided in:

09_Webviews_Guide.md

---

12. Error handling model

The partner app must handle API errors consistently.

At minimum, handle:

expired access token;
invalid or revoked token;
validation errors;
quote expiry;
idempotency conflict;
resource not found;
action not allowed in current transfer state;
temporary service unavailability.

Recommended pattern:

Token expired -> refresh token -> retry once
Quote expired -> request or generate new quote -> restart quote flow
Timeout after write -> retry with same Idempotency-Key
Validation error -> show field-level correction if provided
Unavailable -> show retry message and retry safely

Implementation details are provided in:

05_Headers_Idempotency_Errors.md

---

13. Customer status handling

The customer status returned by the API affects what the partner app should show or allow.

Status	Partner app behavior
`PENDING`	Ask customer to complete onboarding or KYC.
`VALID`	Allow normal transfer flow.
`MONITORED`	Allow flow, but explain that transfer may be reviewed.
`RESTRICTED`	Show customer action message when returned by the API.
`BLOCKED`	Do not allow transfer; show support message.
`CLOSED`	Do not allow transfer; show account closed message.

Do not infer or display internal reasons behind a status. Use only the customer-facing message and next action returned by the API.

---

14. Logging and support expectations

Partner applications should log enough information to support troubleshooting without storing sensitive secrets.

Log:

endpoint;
timestamp;
environment;
X-Correlation-Id;
idempotency key, if used;
HTTP status;
API error code;
sanitized request and response references.

Do not log:

customer passwords;
refresh tokens;
private keys;
full payment instrument details;
unnecessary customer personal data.

When raising a support issue, include the X-Correlation-Id and timestamp.

---

15. What not to build

The partner app must not build parallel logic for actions handled by YCMT.

Do not build:

direct customer authorization decisions from JWT claims;
direct transfer execution outside the YCMT API;
direct funding outside the returned YCMT flow;
direct modification of YCMT transfer state;
direct access to internal customer identifiers;
local assumptions about why a customer or transfer is blocked.

Use API responses and documented flows as the integration contract.

---

16. Next documents

Read these next:

00_README_Quick_Start.md
02_Authentication_Guide.md
03_Core_API_Guide.md
04_End_to_End_Flows.md
05_Headers_Idempotency_Errors.md

Use the OpenAPI files for exact request and response schemas:

api-reference/auth.openapi.yaml
api-reference/core.openapi.yaml