Customer Status and UX Guide

This guide explains how the partner app should handle customer status values returned by the API.

Use this host in API examples:

https://api.yes.cash

---

1. Purpose

Customer status tells the partner app whether the customer can continue with a transfer and what customer experience should be shown.

The partner app should use customer status to:

• decide which screens to show;
• guide the customer to the next action;
• block unavailable actions;
• explain pending or held states clearly;
• avoid exposing internal operational detail.

---

2. Where customer status appears

Customer status may appear in responses such as:

GET /v1/core/profile
GET /v1/core/transfers/{transferId}
GET /v1/core/transfers

The profile endpoint is the normal place to check the customer’s current status before showing transfer features.

Example:

GET https://api.yes.cash/v1/core/profile
Authorization: Bearer <access-token>
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>

Example response shape:

{
  "subscriptionId": "SUB-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "customerStatus": "VALID",
  "kycStatus": "VERIFIED",
  "profileComplete": true
}

---

3. Status values

The partner app may receive these customer status values:

---

4. Status behavior summary

---

5. PENDING

Meaning

The customer has started registration but has not completed required onboarding, profile, or verification steps.

Partner app behavior

The partner app should:

• hide or disable money transfer actions;
• show onboarding completion steps;
• guide the customer to profile completion or KYC;
• avoid showing full transfer flow until status changes.

Recommended customer message

Please complete your profile and verification before sending money.

Recommended next actions

GET /v1/core/profile
POST /v1/core/profile
POST /v1/core/kyc-sessions

---

6. VALID

Meaning

The customer is eligible for the normal transfer flow.

Partner app behavior

The partner app should allow:

• beneficiary creation;
• quote display;
• disclosure review;
• quote acceptance;
• transfer submission;
• device confirmation, where required;
• funding;
• transfer status tracking.

Recommended customer message

Usually no special message is required.

Show the normal transfer experience.

---

7. MONITORED

Meaning

The customer may be allowed to initiate transfers, but one or more transfers may be held for review.

Partner app behavior

The partner app should:

• allow normal customer flow unless the API rejects the specific action;
• show transfer status exactly as returned by the API;
• avoid promising instant completion;
• use pending/review wording when the transfer state requires it.

Recommended customer message

Your transfer is being reviewed. We will update the status shortly.

Do not show

Do not show internal review reasons.

Avoid messages such as:

AML review
Sanctions review
Fraud investigation
Compliance hold reason

---

8. RESTRICTED

Meaning

The customer may need to complete an additional action before transfers can continue or be released.

Examples of customer-facing actions may include:

• update profile information;
• complete verification;
• provide additional information;
• retry failed verification.

Partner app behavior

The partner app should:

• check the API response for required next action;
• send the customer to the relevant remediation flow;
• avoid guessing the reason;
• show only the message or remediation guidance returned by the API.

Recommended customer message

We need some additional information before you can continue.

Recommended next action

GET /v1/core/profile

Then follow the returned profile, KYC, or remediation state.

---

9. BLOCKED

Meaning

The customer cannot use transfer services.

Partner app behavior

The partner app should:

• hide or disable new transfer creation;
• avoid allowing quote acceptance;
• avoid allowing transfer submission;
• show a neutral support message;
• not expose internal reasons.

Recommended customer message

Transfers are currently unavailable for this account. Please contact support.

Do not show

Do not display internal reason categories or investigation details.

---

10. CLOSED

Meaning

The customer relationship is closed.

Partner app behavior

The partner app should:

• prevent new transfer journeys;
• prevent beneficiary creation for new transfers;
• show account closed messaging;
• allow only any read-only screens that the API still permits;
• direct the customer to support if appropriate.

Recommended customer message

This account is closed. Please contact support if you need help.

---

11. KYC status vs customer status

Customer status is not the same as KYC status.

Example:

{
  "customerStatus": "PENDING",
  "kycStatus": "NOT_STARTED",
  "profileComplete": false
}

Partner app interpretation:

Customer must complete profile and KYC before transfer flow.

Example:

{
  "customerStatus": "VALID",
  "kycStatus": "VERIFIED",
  "profileComplete": true
}

Partner app interpretation:

Customer can use normal transfer flow.

---

12. Recommended screen routing

---

13. Transfer-specific UX

A customer may have a general customer status and each transfer may also have its own transfer state.

Always use transfer detail for transfer-specific screens:

GET /v1/core/transfers/{transferId}

Examples:

---

14. Error-code interaction

Sometimes customer status appears as an error.

Example:

{
  "error": {
    "code": "customer.statusInsufficient",
    "message": "Customer status does not allow this action.",
    "remediation": "remediation.customer_ux.complete_verification"
  },
  "correlationId": "5e4f3c72-4c3c-46e5-82e6-5a7c6d7218af"
}

Partner app behavior:

• use error.code for logic;
• use remediation to choose the next UX step;
• avoid interpreting internal reasons;
• fetch profile if the next step is unclear.

---

15. Suggested customer messages

Partner apps may adapt wording to their brand tone, but must not add internal reasons.

---

16. What not to show customers

Do not show:

• internal reason codes;
• sanctions terminology;
• AML review details;
• fraud investigation labels;
• operator names;
• internal approval levels;
• internal evidence requirements;
• database identifiers;
• MasterCustomerId;
• raw technical stack traces.

Use neutral, customer-action-focused language.

---

17. Customer support handoff

If the customer needs support, provide:

• customer-facing reference if available;
• transfer reference, if transfer-specific;
• timestamp;
• support category;
• correlation ID if available.

Do not ask the customer to provide:

• access token;
• refresh token;
• OTP;
• password;
• device private key;
• full payment instrument data.

---

18. Refreshing status

Partner apps should refresh customer status:

• after login;
• after profile submission;
• after KYC completion;
• before starting a transfer;
• after a blocked action;
• when returning from webview;
• when app resumes after a long idle period.

Recommended endpoint:

GET /v1/core/profile

---

19. Caching guidance

Partner apps may cache status briefly for UI performance, but should not rely on stale status for money-moving actions.

Recommended:

---

20. Common implementation mistakes

---

21. Implementation checklist

Before certification, confirm that the partner app:

• reads customer status from profile;
• routes PENDING customers to onboarding/KYC;
• allows normal flow for VALID;
• handles MONITORED with pending/review messaging where needed;
• routes RESTRICTED customers to remediation;
• blocks new transfers for BLOCKED;
• blocks new transfers for CLOSED;
• never shows internal reason codes;
• never shows MasterCustomerId;
• refreshes status after webview return;
• refreshes status before transfer initiation;
• maps status-related errors to safe customer messages;
• logs correlation IDs for support.