YCMT EU Partner Developer Guide
Errors, Statuses and Retry Guide
Version 1.0 - Partner-safe developer documentation
| Field | Value |
|---|
| Document | 60_YCMT_EU_PartnerDev_Errors_Statuses_And_Retry_Guide_v1_0.docx |
| Audience | YCMT EU partner application developers and QA teams |
| Scope | Error handling, status handling, remediation, retry, idempotency, pagination and rate-limit behaviour |
| Perimeter | YCMT EU only |
| Disclosure level | Partner-safe. Internal YCMT implementation details are intentionally excluded. |
Partner-safe boundary
This guide explains how a partner application should react to YCMT API responses. It does not describe YCMT internal systems, internal identifiers, risk rules, approval levels, or regulatory reason codes. |
|---|
1. Purpose of this guide
This guide helps partner developers build resilient YCMT EU integrations. It explains what the partner application should do when an API call succeeds, fails, requires customer action, should be retried, or should be escalated.
- Interpret customer, KYC, beneficiary, quote, transfer, funding and refund statuses.
- Handle API error responses consistently.
- Use idempotency keys correctly.
- Retry only when retrying is safe.
- Use pagination and rate-limit responses correctly.
- Show customer-safe messages without exposing internal compliance or risk logic.
2. Core handling principles
| Principle | Partner application behaviour |
|---|
| Do not infer internal decisions | Use the documented status or error code. Do not infer AML, sanctions, fraud, or internal review reasons. |
| Use customer-safe remediation | Display only the recommended action: retry, complete KYC, contact support, wait for review, or restart the flow. |
| Retry safely | Retry only retryable technical errors, timeouts, and documented idempotent requests. |
| Preserve idempotency | For mutation requests requiring idempotency, send the same idempotency key when retrying the same business action. |
| Treat unknown codes conservatively | Show a generic error, log the correlation ID, and contact YCMT support if the issue continues. |
| Never expose raw technical details to customers | Do not display stack traces, provider messages, gateway details, or internal-looking text to customers. |
3. Standard error response
YCMT APIs return structured error responses. Partner applications should use the error code for logic and the remediation or hint fields for user experience and developer handling.
| Field | Meaning | Partner use |
|---|
| code | Stable machine-readable error code. | Use for branching logic. |
| message | Short human-readable description. | Useful for logs; customer-facing text should normally use partner-approved copy. |
| correlationId | YCMT trace identifier for support. | Store and provide to YCMT support. |
| hint | Developer-oriented handling guidance. | Use for integration handling, not direct customer copy. |
| remediation | Customer-action category or UX guidance. | Map to partner-approved customer copy. |
| details | Optional validation details where safe to expose. | Use to highlight form fields or invalid inputs. |
Example:
{
"error": {
"code": "quote.expired",
"message": "The quote has expired.",
"correlationId": "f5420b90-7d02-4cb0-b9c8-0ebc5d8a2b8a",
"hint": "Create a new quote and repeat the acceptance flow.",
"remediation": "Ask the customer to review a fresh quote."
}
}
4. Error categories and expected handling
| Category | Typical meaning | Default partner handling |
|---|
| auth.* | Access token, session, login or authentication problem. | Refresh token where appropriate, restart login, or ask customer to authenticate again. |
| validation.* | Request is malformed or unsupported. | Fix input, highlight the relevant field, do not automatically retry unchanged. |
| customer.* | Customer status or customer eligibility prevents the requested action. | Follow remediation: complete onboarding, wait, or contact support. |
| kyc.* | KYC session, document capture or verification issue. | Guide customer to complete or repeat the KYC step. |
| beneficiary.* | Beneficiary state, validation or screening issue. | Ask customer to correct details, choose another method, or wait for review. |
| quote.* | Quote is expired, invalid, unavailable or mismatched. | Generate a fresh quote and repeat disclosure/acceptance. |
| disclosure.* | Required disclosure has not been retrieved or is no longer current. | Fetch disclosure again before acceptance. |
| transfer.* | Transfer state does not allow the requested action. | Refresh transfer status and adjust UI actions. |
| funding.* | Funding session, payment or webview issue. | Refresh status, restart funding if permitted, or show pending state. |
| device.* | Device registration or confirmation assertion issue. | Re-register device, retry confirmation, or escalate if persistent. |
| partner.* / subscription.* | Partner app or partner-customer relationship issue. | Do not retry blindly; contact YCMT support. |
| idempotency.* | Idempotency key missing, reused incorrectly, or conflicting. | Use a correct key for new action or same key for same retry. |
| pagination.* | Invalid cursor, date range, or pagination parameter. | Reset pagination and request a valid page. |
| internal.* / network.* | Temporary YCMT or network unavailability. | Retry using backoff if safe; otherwise show temporary issue. |
5. Customer status handling
Customer status is a partner-visible operational indicator. It tells the partner application whether the customer can continue a journey and which customer action, if any, is required. It does not disclose internal review reasons.
| Status | Meaning for partner app | Recommended UX |
|---|
| PENDING | Customer exists but onboarding or required profile/KYC steps are incomplete. | Guide the customer to complete profile and KYC. Do not show money-moving actions as available. |
| VALID | Customer is eligible to use the service, subject to normal controls. | Allow the standard transfer journey. |
| MONITORED | Customer may initiate activity, but transfers may be held for YCMT review. | Allow the journey, then show review/pending status if the transfer is held. Do not ask customer for documents unless YCMT asks. |
| RESTRICTED | Customer may need to complete additional remediation before transfers can be released. | Guide the customer to the requested remediation step when provided. |
| BLOCKED | Customer cannot transact. | Stop money-moving actions and show a generic contact-support message. |
| CLOSED | Customer relationship is closed. | Do not allow new activity. Show a generic contact-support or account-closed message as approved by YCMT. |
Important
Do not tell the customer that a transfer or account is under AML, sanctions, fraud, or law-enforcement review unless YCMT has supplied an approved customer communication. |
|---|
6. KYC and beneficiary status handling
| Status family | Typical statuses | Partner handling |
|---|
| KYC session | started, pending, completed, failed, expired | Launch or resume the YCMT KYC webview. If expired, create a new KYC session. If failed, follow the supplied remediation. |
| KYC outcome | pending, approved, remediation_required, rejected | Use the status to control the next UI step. Do not expose internal verification reasons unless explicitly provided for customer display. |
| Beneficiary | active, pending_review, blocked, archived | Allow transfer only to active beneficiaries. Pending review should show a waiting state. Archived beneficiaries should not be selectable for new transfers. |
7. Quote and disclosure status handling
| Condition | Meaning | Partner handling |
|---|
| Quote available | The customer can review the quote. | Show amount, fees, FX rate, delivery estimate and expiry. |
| Quote expired | The quote can no longer be accepted. | Create a new quote and require the customer to review the latest disclosure before acceptance. |
| Disclosure required | The customer must see the required disclosure before acceptance. | Fetch and display the disclosure before quote acceptance. |
| Disclosure stale | Quote or regulatory disclosure is no longer current. | Fetch a fresh disclosure and repeat acceptance. |
| Quote mismatch | The signed quote does not match the customer, partner or current conditions. | Do not retry unchanged. Generate a new quote and contact support if repeated. |
8. Transfer status handling
The partner app should display transfer progress from the transfer status returned by YCMT. Do not infer finality from payment-provider or partner-side events unless YCMT status confirms it.
| Status group | Meaning | Partner UI behaviour |
|---|
| Draft / registered | Transfer has been created or registered but not fully submitted or funded. | Allow the next required action, such as confirmation or funding. |
| Validated / awaiting confirmation | Transfer passed preliminary checks and may require device confirmation. | Prompt for required confirmation step. |
| Funding / funded | Funding webview has been opened or funding is being confirmed. | Show payment-in-progress state and poll status. |
| Held / review | Transfer is accepted but held for YCMT or customer action. | Show pending/review state. Use remediation if supplied. |
| In payout / sent | Transfer is being processed through the payout route. | Show in-progress state and estimated delivery. |
| Paid / completed | Transfer is completed. | Show completion receipt/status. |
| Cancelled / refunded | Transfer was cancelled and refund process may apply. | Show cancellation and refund status separately. |
| Failed / rejected | Transfer cannot continue. | Show safe failure message and next available action. |
9. Retry rules
| Situation | Retry? | How to handle |
|---|
| HTTP timeout before response | Yes, if request is idempotent or protected by idempotency key. | Retry with the same idempotency key for the same business action. |
| HTTP 429 rate limited | Yes, after waiting. | Respect Retry-After when provided; otherwise use exponential backoff. |
| HTTP 5xx temporary error | Usually yes. | Retry with backoff for safe/idempotent calls. For transfer-affecting calls, keep same idempotency key. |
auth.tokenExpired | Yes, after refresh. | Refresh token if possible, then retry the original request once. |
| validation.* | No unchanged retry. | Correct the request first. |
quote.expired | No unchanged retry. | Create a fresh quote and repeat disclosure/acceptance. |
customer.statusBlocking | No. | Stop the flow and show approved contact-support guidance. |
idempotency.conflict | No unchanged retry. | Check whether the previous business action is already completed; do not create duplicate intent. |
Backoff recommendation
For retryable temporary errors, use exponential backoff with jitter. A practical default is 1s, 2s, 4s, 8s, then stop and show a temporary issue. Do not run infinite retries from the customer app. |
|---|
10. Idempotency keys
Idempotency protects customers from duplicate business actions when the app retries after a timeout or network failure.
| Rule | Explanation |
|---|
| One key per business action | Generate a new unique key when the customer starts a new action, such as accepting a new quote or submitting a new transfer. |
| Reuse the same key on retry | If the app did not receive a response and retries the exact same action, send the same key. |
| Do not reuse across different actions | A key used for one quote acceptance must not be reused for a different quote or transfer. |
| Store until final outcome is known | Keep the key long enough to reconcile retries, app restarts, and network failures. |
| Use UUID format | Use a random UUID v4 or equivalent high-entropy value. |
| Endpoint type | Idempotency guidance |
|---|
| Read/list endpoints | Usually no idempotency key required. Safe to retry. |
| Create/update/action endpoints | Use idempotency where documented. Required for money-moving or state-changing actions. |
| Quote acceptance | Use idempotency key and do not duplicate acceptance attempts with new keys unless intentionally starting a new business action. |
| Transfer submit/confirm/cancel | Use idempotency key where documented. Reuse on retry of same action. |
11. Pagination and list handling
| Topic | Guidance |
|---|
| Cursor pagination | Use the next cursor returned by YCMT. Do not invent or modify cursor values. |
| Empty list | Treat as a valid result, not an error. |
| Invalid cursor | Restart the list request from the first page. |
| Date filters | Use ISO date/time formats where documented. Keep date ranges reasonable. |
| Sorting | Use documented sort parameters only. If unsupported, use default order. |
| UI refresh | For transfer lists, refresh after important actions such as submit, confirm, cancel or funding completion. |
12. Rate limits and throttling
| Condition | Partner behaviour |
|---|
| 429 returned | Stop immediate repeat calls. Respect Retry-After if present. |
| Repeated 429s | Reduce polling frequency and check for app loops. |
| Status polling | Use a reasonable interval. Do not poll multiple times per second. |
| Customer action screens | Poll only when the customer is waiting for visible progress, and stop after terminal state. |
| Background jobs | Batch responsibly and avoid bursts during peak hours. |
13. Logging and support escalation
| Log this | Do not log this |
|---|
| correlationId | Access tokens or refresh tokens |
| HTTP status and error code | Passwords, OTPs or full authentication secrets |
| Endpoint and timestamp | Full payment instrument details |
| Partner-side request ID / idempotency key | Full identity document images or sensitive KYC payloads |
| subscriptionId where returned | Internal-looking technical payloads not needed for support |
When contacting YCMT support, include the environment, timestamp, endpoint, correlation ID, partner-side request ID, and a short description of the customer journey step. Do not send customer secrets or payment credentials by email or ticket unless YCMT provides a secure channel.
14. Customer-safe message examples
| Situation | Customer-safe message pattern |
|---|
| Temporary service issue | We could not complete this step right now. Please try again shortly. |
| Token expired/session ended | For your security, please sign in again. |
| KYC incomplete | Please complete the verification step to continue. |
| Quote expired | This quote has expired. Please review a new quote before continuing. |
| Transfer under review | Your transfer is being reviewed. We will update the status when review is complete. |
| Customer cannot proceed | We cannot complete this request in the app. Please contact support. |
Do not disclose
Avoid wording that mentions sanctions, AML investigation, fraud suspicion, regulatory filing, law-enforcement request, internal risk score, or exact reason codes unless YCMT has supplied approved text. |
|---|
15. Developer implementation checklist
- Every API call stores the returned correlation ID.
- Authentication errors trigger refresh or login restart as documented.
- Money-moving retries reuse the same idempotency key for the same action.
- Quote expiration creates a fresh quote and repeats disclosure before acceptance.
- Transfer status polling stops on terminal states.
- 429 responses respect Retry-After or exponential backoff.
- Unknown error codes fall back to a safe generic message and support escalation.
- Customer-facing messages do not expose internal risk or compliance reasons.
- Logs do not contain tokens, passwords, OTPs, card details or unnecessary KYC data.
- QA covers timeout, duplicate-submit, expired-token, expired-quote and rate-limit scenarios.
| Document | Use |
|---|
60_YCMT_EU_PartnerDev_Getting_Started_v1_0.docx | Entry point for integration setup. |
60_YCMT_EU_PartnerDev_API_Guide_v1_0.docx | Human-readable API reference. |
60_YCMT_EU_PartnerDev_Flows_Guide_v1_0.docx | End-to-end customer journeys. |
60_YCMT_EU_PartnerDev_Security_And_Signing_Guide_v1_0.docx | Token handling, device confirmation, quote signing and webhooks. |
60_YCMT_EU_PartnerDev_Sandbox_And_GoLive_Guide_v1_0.docx | Sandbox testing and production readiness. |