YCMT EU Partner Developer Flows Guide
Version 1.0 | Partner-safe integration guide
For approved partner developers integrating with the YCMT EU white-label remittance API.
| Field | Value |
|---|---|
| Document | 60_YCMT_EU_PartnerDev_Flows_Guide_v1_0.docx |
| Perimeter | YCMT EU only |
| Audience | Approved partner developers, partner technical architects, partner QA teams |
| Scope | End-to-end customer and transfer journeys using the YCMT EU partner-facing API surface |
| Status | Draft v1.0 for partner developer pack |
| Internal detail policy | Partner-safe: no internal system design, no internal identifiers, no internal decision logic |
1. Purpose
This guide explains how the YCMT EU API calls fit together into complete customer journeys. It is designed for partner developers who need to build a working customer experience without reading internal architecture documents.
Partner-safe scope: This document explains the external API behaviour only. It intentionally does not describe YCMT internal systems, internal identifiers, internal routing, internal risk rules, or internal approval workflows.
2. What this guide covers
- New customer onboarding from registration to first transfer readiness.
- Returning customer login and token refresh patterns.
- KYC capture and remediation handling.
- Beneficiary creation and validation handling.
- Quote, disclosure, acceptance, transfer creation, confirmation, funding, and transfer status polling.
- Cancellation and refund-facing status handling.
- Customer-status scenarios that require partner UX handling or escalation.
3. High-level integration sequence
| Step | Capability | Main API area | Partner app outcome |
|---|---|---|---|
| 1 | Register or log in customer | Auth API | Customer receives an access token for customer-context calls. |
| 2 | Register customer device when required | Auth API | Customer device is ready for protected transfer confirmation. |
| 3 | Capture profile and KYC | Core API + YCMT-hosted webview | Customer becomes eligible to transact once YCMT approves the KYC outcome. |
| 4 | Create or select beneficiary | Core API | Customer selects a payout recipient. |
| 5 | Quote and disclosure | Core API + partner pricing surface where applicable | Customer sees price, FX, fees, recipient amount, and required disclosures. |
| 6 | Accept quote and submit transfer | Core API | YCMT validates the request and creates a transfer flow. |
| 7 | Confirm transfer and complete funding | Core API + YCMT-hosted webview | Customer confirms and completes funding through YCMT-controlled flow. |
| 8 | Poll status and handle outcome | Core API | Partner app shows transfer progress and final outcome. |
Golden rule: Any action that creates a financial obligation or moves money must be performed in the customer context using the documented customer access token. Partner server-side credentials alone must not be used to create or execute customer transfers.
4. Common flow rules
| Rule | Partner developer requirement |
|---|---|
| Access token | Send the customer access token in the Authorization header on every customer-context request. |
| Subscription ID | Treat subscriptionId as the partner-facing customer reference. Do not attempt to infer or request internal customer identifiers. |
| Idempotency | Send idempotency keys on write operations where specified by the API guide. Reuse the same key only for retrying the same business action. |
| Correlation ID | Send a correlation ID where supported and log it for support escalation. |
| Webviews | Launch YCMT-provided webview URLs inside the approved app/browser container and listen for completion/closure events. |
| Polling | Use documented polling cadence and stop polling when a terminal status is reached. |
| Errors | Handle error.code, hint, and remediation identifiers. Do not branch on free-text messages. |
| Customer messaging | Use YCMT-approved customer-safe wording. Do not reveal or guess internal compliance reasons. |
5. Flow 1 - New customer onboarding
Use this flow when a customer uses the partner app for the first time and does not yet have a YCMT EU customer session.
| Order | Action | Endpoint / surface | Expected result |
|---|---|---|---|
| 1 | Start registration with customer identifier | POST /v1/auth/register/start | YCMT returns a registration session or neutral response according to the API contract. |
| 2 | Verify OTP | POST /v1/auth/register/verify-otp | OTP is accepted and the registration session may proceed. |
| 3 | Set password / complete registration | POST /v1/auth/register/set-password or documented completion endpoint | Customer receives tokens and partner-visible subscriptionId. |
| 4 | Register device if required | POST /v1/auth/device-registration/start and /complete | Customer device becomes eligible for protected confirmation flows. |
| 5 | Submit customer profile | POST /v1/core/profile | Profile is captured for YCMT review and KYC flow. |
| 6 | Start KYC session | POST /v1/core/kyc-sessions | YCMT returns KYC session information and webview URL. |
| 7 | Launch KYC webview | YCMT-hosted webview | Customer completes document/liveness or other required steps. |
| 8 | Check status | GET /v1/core/profile and/or GET /v1/core/kyc-sessions/{kycSessionId} | App shows whether the customer is ready, pending, or requires action. |
- UX requirement: Do not present the customer as ready to send money until YCMT returns an eligible status through the documented API response.
- Support requirement: If the customer is asked for more information, guide them back to the YCMT-provided remediation path. Do not ask the customer to send documents outside the approved flow.
6. Flow 2 - Returning customer login
Use this flow when a customer already has credentials and is returning to the partner app.
| Order | Action | Endpoint / surface | Expected result |
|---|---|---|---|
| 1 | Start login | POST /v1/auth/start | YCMT returns the next login step using a non-enumerating response pattern. |
| 2 | Submit credentials | POST /v1/auth/login | Customer receives access token, refresh token, expiry, and subscriptionId if login succeeds. |
| 3 | Handle MFA if required | Login response challenge fields, where applicable | App prompts the customer for the required verification step. |
| 4 | Refresh token before expiry | POST /v1/auth/refresh | New access token is issued if refresh is valid. |
| 5 | Logout | POST /v1/auth/logout | App clears local session material and follows documented logout result. |
Do not enumerate customers: The app must not tell a user whether an identifier exists based on login or password-reset responses. Use neutral wording such as: "If your details are recognised, continue with the next step shown."
7. Flow 3 - KYC completion and remediation
The partner app hosts the user experience, but YCMT controls the KYC session, review, outcome, and remediation decisions.
| Scenario | Partner app behaviour |
|---|---|
| KYC not started | Show a prompt to complete verification and call POST /v1/core/kyc-sessions. |
| KYC in progress | Show pending state. Avoid repeated session creation unless the current session is expired or the API instructs retry. |
| KYC approved | Allow the customer to proceed to beneficiary, quote, and transfer flows subject to other checks. |
| More information required | Show the remediation action returned by YCMT and route customer to the approved webview or upload step. |
| KYC rejected or customer blocked | Show generic support-oriented wording. Do not reveal or guess compliance reasons. |
- Never allow the partner app or partner staff to override a KYC outcome.
- Never collect KYC documents through unapproved email, chat, or partner-operated upload forms.
- Always preserve correlation IDs for KYC support escalation.
8. Flow 4 - Beneficiary creation
A beneficiary is created in the customer context and is visible only within the partner/customer relationship that created it.
| Order | Action | Endpoint / surface | Expected result |
|---|---|---|---|
| 1 | List existing beneficiaries | GET /v1/core/beneficiaries | App displays saved beneficiaries available to this customer in this partner channel. |
| 2 | Create beneficiary | POST /v1/core/beneficiaries | YCMT validates recipient details and corridor/payout requirements. |
| 3 | Fetch beneficiary detail | GET /v1/core/beneficiaries/{beneficiaryId} | App confirms recipient details before quote or transfer. |
| 4 | Archive beneficiary if requested | POST /v1/core/beneficiaries/{beneficiaryId}/archive | Beneficiary is no longer available for new transfers if archive succeeds. |
Beneficiary validation: If YCMT rejects a destination country, payout method, mobile-money provider, account format, or recipient detail, the app must display the documented remediation and allow the customer to correct the input where permitted.
9. Flow 5 - Quote, disclosure, and acceptance
The quote flow must ensure the customer sees and accepts the price, FX, fees, recipient amount, and required disclosures before the transfer is submitted.
| Order | Action | Endpoint / surface | Expected result |
|---|---|---|---|
| 1 | Create or retrieve quote according to partner pricing setup | Documented quote surface | Customer sees send amount, receive amount, FX, fees, total, corridor, and expiry. |
| 2 | Retrieve disclosure | GET /v1/core/quotes/{quoteId}/disclosure | App displays required remittance disclosure before acceptance. |
| 3 | Accept quote | POST /v1/core/quotes/{quoteId}/accept | YCMT validates quote, customer, partner, corridor, expiry, and eligibility before accepting. |
| 4 | Handle expired quote | Error response, e.g. quote expired category | App asks customer to refresh price and restart acceptance with a fresh quote. |
- Show the quote expiry clearly in the UI.
- Do not reuse an expired quote.
- Do not alter quote values after the customer has accepted them.
- If the partner operates quote signing, follow the Security and Signing Guide for the exact signing process.
10. Flow 6 - Transfer creation and confirmation
The transfer flow starts only after the customer has accepted a valid quote and selected a valid beneficiary.
| Order | Action | Endpoint / surface | Expected result |
|---|---|---|---|
| 1 | Submit transfer | POST /v1/core/transfers/{transferId}/submit or documented submit endpoint | YCMT validates customer, quote, beneficiary, corridor, limits, and transfer rules. |
| 2 | Retrieve transfer detail | GET /v1/core/transfers/{transferId} | App receives current transfer status and next customer action. |
| 3 | Confirm transfer where required | POST /v1/core/transfers/{transferId}/confirm | Customer confirms through the protected confirmation mechanism. |
| 4 | Handle confirmation challenge expiry | Documented error response | App asks customer to refresh transfer detail and repeat the confirmation step if allowed. |
Confirmation control: The partner app must not simulate, skip, or replace YCMT transfer confirmation. If confirmation is required, the customer must complete the documented confirmation step.
11. Flow 7 - Funding webview
Funding is completed through a YCMT-provided flow. The partner app is the display host; YCMT controls the regulated funding process.
| Order | Action | Partner app requirement |
|---|---|---|
| 1 | Receive funding webview URL | Open the URL using the approved in-app browser or redirect pattern. |
| 2 | Customer completes funding | Do not collect payment-card, bank, or funding credentials outside the YCMT flow. |
| 3 | Webview closes or redirects | Use the documented completion/closure signal. Do not assume success solely because the webview closed. |
| 4 | Poll transfer detail | Call GET /v1/core/transfers/{transferId} until the status confirms the funding outcome or further action is required. |
- Do not store payment credentials unless explicitly approved in a separate documented PCI/payment-provider scope.
- Always rely on YCMT transfer status for the authoritative funding outcome.
- Show a pending message if funding confirmation is delayed.
12. Flow 8 - Transfer status polling
Use transfer polling to keep the customer informed. The transfer detail response is the authoritative source for what the partner app should show next.
| Status category | Partner app behaviour |
|---|---|
| Action required | Prompt the customer to complete the indicated next step, such as confirmation, funding, or remediation. |
| In progress | Show progress. Poll at the documented interval and avoid aggressive polling. |
| Held for review | Show neutral pending wording. Do not state or imply the internal reason for the hold. |
| Completed / paid | Show completion and receipt details when returned by the API. |
| Canceled / refunded / failed | Show customer-safe outcome and next available action, such as refund status or support contact. |
Polling discipline: Stop polling when the transfer reaches a terminal state. If the API returns a retry-after or rate-limit response, respect it.
13. Flow 9 - Cancellation and refund handling
Cancellation availability depends on the transfer state and network/payment-provider outcome. A cancellation request is not the same as a guaranteed cancellation.
| Order | Action | Expected behaviour |
|---|---|---|
| 1 | Customer requests cancellation | App checks current transfer detail and whether cancellation is available. |
| 2 | Submit cancellation | Call the documented cancellation endpoint if cancellation is permitted. |
| 3 | Poll transfer detail | Show pending cancellation while YCMT coordinates the outcome. |
| 4 | Handle final outcome | Show canceled, not cancelable, refund pending, refund succeeded, or refund failed wording according to API response. |
- Do not promise that a transfer can be canceled until the API confirms the cancellation outcome.
- Do not promise refund timing unless returned or approved by YCMT.
- Escalate unclear or disputed cancellation outcomes using the support process and correlation ID.
14. Flow 10 - Customer status scenarios
YCMT may return a customer status or remediation condition that affects what the customer can do. The partner app must handle these states without exposing internal reasons.
| Customer-facing condition | What the partner app should do |
|---|---|
| Customer not yet ready to transact | Guide the customer to complete profile or KYC steps. |
| Customer valid and eligible | Allow normal transfer journey, subject to quote, beneficiary, corridor, and transfer checks. |
| Transfer accepted but held for review | Show neutral pending wording and continue status polling. |
| Customer action required | Show the remediation action returned by YCMT, such as updating documents or completing verification. |
| Customer cannot transact | Show generic support wording and provide approved support channel. |
| Customer relationship closed | Do not offer new transfers. Show approved support/contact wording only. |
Do not disclose internal reasons: For blocked, closed, sanctions, fraud, AML, or review-related conditions, partner apps and partner staff must use approved generic wording. Do not guess, display, or disclose internal reasons or evidence.
15. Recommended implementation order
- Implement registration and login flows in sandbox.
- Implement token storage, refresh, logout, and neutral authentication error handling.
- Implement profile and KYC webview launch/return handling.
- Implement beneficiary list/create/detail/archive.
- Implement quote display, disclosure display, and quote acceptance.
- Implement transfer submit, confirmation, funding webview, and status polling.
- Implement cancellation and refund-facing status handling.
- Implement error, remediation, idempotency, pagination, and rate-limit handling.
- Run the Sandbox and Go-Live Guide test suite.
- Submit evidence and activate production credentials only after YCMT confirms readiness.
16. Partner developer checklist
| Area | Minimum readiness check |
|---|---|
| Authentication | Customer can register, log in, refresh, and log out in sandbox. |
| KYC | App can launch KYC webview and handle pending, success, and remediation outcomes. |
| Beneficiaries | App validates and displays beneficiary details correctly. |
| Quotes | App displays price, FX, fees, expiry, and disclosure before acceptance. |
| Transfers | App supports submit, confirm, funding, polling, and terminal outcomes. |
| Errors | App handles retryable, non-retryable, remediation, and rate-limit responses. |
| Security | Tokens and signing keys are protected and sensitive values are not logged. |
| Support | Correlation IDs are logged and support escalation path is implemented. |
17. Related partner developer documents
| Document | When to use it |
|---|---|
| Getting Started Guide | Before reading this guide; gives the integration overview and first calls. |
| API Guide | When implementing individual endpoints and request/response schemas. |
| Errors, Statuses, and Retry Guide | When implementing resilience, remediation, idempotency, pagination, and rate-limit behaviour. |
| Security and Signing Guide | When implementing device confirmation, quote signing, webhook verification, and token handling. |
| Sandbox and Go-Live Guide | When preparing test evidence and production activation. |
| OpenAPI and Postman Pack | When generating clients or running executable examples. |
18. Boundary reminder
The partner app provides the branded customer experience. YCMT controls customer authentication, customer eligibility, KYC and AML decisions, transaction approval, funding flow, settlement, transfer status, and regulatory liability. Partner developers must not design flows that bypass the customer-context API or allow partner systems to create or execute transfers without the customer completing the documented YCMT flow.