Guide

End-to-End Flows

Main customer journeys and recommended call order.

End-to-End Flows

This guide shows the main customer journeys that a partner app must implement when integrating with the YesCash API.

Use this host in all examples:

https://api.yes.cash

The flows below are intentionally practical. They show the call order, what the partner app must store, and what the app should do next.

---

1. Common request pattern

Most calls follow the same structure.

Anonymous Auth calls

Used before the customer has an access token.

POST https://api.yes.cash/v1/auth/start
Content-Type: application/json
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>

Customer-authenticated calls

Used after login or registration.

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

Idempotent action calls

For actions that may be retried safely, send an idempotency key.

POST https://api.yes.cash/v1/core/transfers/{transferId}/submit
Authorization: Bearer <access-token>
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>
Idempotency-Key: <uuid>
Content-Type: application/json

---

2. New customer onboarding flow

Use this flow when a customer is registering for the first time.

Customer enters identifier
  → Register start
  → OTP verification
  → Set password / complete registration
  → Receive access token
  → Register device
  → Continue to profile and KYC

Step 1 — Start registration

POST /v1/auth/register/start

Partner app sends:

customer identifier, such as email or phone;
preferred language, if supported;
correlation ID.

Partner app receives:

registration reference;
OTP delivery confirmation or neutral response;
next-step instruction.

Step 2 — Verify OTP

POST /v1/auth/register/verify-otp

Partner app sends:

registration reference;
OTP code entered by customer.

Partner app receives:

OTP verification result;
registration continuation token or equivalent continuation reference.

Step 3 — Complete registration

Use the registration completion endpoint defined in the Auth API reference.

Partner app sends:

registration continuation reference;
customer password.

Partner app receives:

access token;
refresh token;
token expiry;
subscriptionId, if returned by the API;
next-step guidance.

Step 4 — Register device

POST /v1/auth/device-registration/start
POST /v1/auth/device-registration/complete

Partner app must:

generate the customer device key pair;
keep the private key on the device;
send the public key and signed registration proof;
store the device registration status locally.

Step 5 — Continue to profile and KYC

After registration and device setup, continue to:

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

---

3. Returning customer login flow

Use this flow when a registered customer signs in.

Customer enters identifier
  → Login start
  → Login completion
  → Receive access token
  → Refresh local session
  → Call Core API

Step 1 — Start login

POST /v1/auth/start

Partner app sends:

identifier;
correlation ID.

Partner app receives:

login attempt reference;
next credential step;
neutral response where applicable.

Step 2 — Complete login

POST /v1/auth/login

Partner app sends:

login attempt reference;
password or required credential response.

Partner app receives:

access token;
refresh token;
expiry information;
subscriptionId, if returned;
customer session information.

Step 3 — Call first Core API endpoint

GET /v1/core/profile

Use this call to load:

customer profile state;
KYC state;
customer status;
next action expected from the customer.

---

4. Token refresh flow

Use refresh before the access token expires or when the API returns auth.tokenExpired.

Access token close to expiry
  → Refresh token
  → Receive new access token
  → Retry original request

Step 1 — Refresh token

POST /v1/auth/refresh

Partner app sends:

refresh token.

Partner app receives:

new access token;
updated expiry;
optionally rotated refresh token, if the API returns one.

Step 2 — Retry original request

Retry the failed request with:

new Authorization header;
same Idempotency-Key if retrying the same idempotent business action;
new or same X-Correlation-Id, depending on partner logging policy.

---

5. Logout flow

Use logout when the customer explicitly signs out.

Customer taps logout
  → Call logout
  → Clear local tokens
  → Clear local sensitive session state

Step 1 — Logout

POST /v1/auth/logout

Partner app sends:

current access token.

Step 2 — Clear local session

Partner app must clear:

access token;
refresh token;
cached customer data;
sensitive screen state.

---

6. Profile and KYC flow

Use this flow before allowing the customer to initiate transfers.

Get profile
  → Submit missing profile fields
  → Start KYC session
  → Open KYC webview
  → Poll KYC session
  → Continue when customer is eligible

Step 1 — Read profile

GET /v1/core/profile

Partner app reads:

profile completion state;
KYC status;
customer status;
missing customer actions.

Step 2 — Submit profile

POST /v1/core/profile

Partner app sends required identity attributes.

Step 3 — Start KYC session

POST /v1/core/kyc-sessions

Partner app receives:

kycSessionId;
KYC webview URL;
session expiry.

Step 4 — Open KYC webview

The partner app opens the returned webview URL.

The partner app must:

show the webview inside the approved app/browser context;
handle customer cancellation;
handle timeout;
return the customer to the app after completion.

Step 5 — Poll KYC session

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

Continue polling until the API returns a terminal or actionable state.

---

7. Add beneficiary flow

Use this flow to create a recipient before creating or accepting transfers.

Customer enters beneficiary details
  → Create beneficiary
  → Check beneficiary state
  → Continue when beneficiary is usable

Step 1 — Create beneficiary

POST /v1/core/beneficiaries

Partner app sends:

beneficiary name;
destination country;
payout method;
account, wallet, or payout details required for the selected method.

Partner app receives:

beneficiaryId;
beneficiary state;
masked payout details;
next action if more information is required.

Step 2 — List beneficiaries

GET /v1/core/beneficiaries

Use this endpoint to show saved beneficiaries to the customer.

Step 3 — Read beneficiary detail

GET /v1/core/beneficiaries/{beneficiaryId}

Use this endpoint before building quote or transfer screens.

---

8. Quote, disclosure and acceptance flow

Use this flow when the customer selects amount, beneficiary, and payout method.

Partner pricing engine creates signed quote
  → Customer reviews quote
  → App fetches disclosure
  → Customer accepts
  → API validates signed quote
  → Quote accepted

Step 1 — Create signed quote

The partner system prepares a signed quote according to the quote signing guide.

The quote must be:

signed using the required algorithm;
bound to the correct customer subscription;
within validity period;
consistent with the amount, corridor, fees, and payout details shown to the customer.

Step 2 — Fetch quote if required

GET /v1/core/quotes/{quoteId}

Use this endpoint to retrieve current quote details when the quote already exists in the API context.

Step 3 — Fetch disclosure

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

Show the customer:

amount to send;
fees;
exchange rate;
amount to receive;
recipient information;
transfer timing information where returned.

Step 4 — Accept quote

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

Partner app sends:

accepted quote reference;
required signed quote artefact, if required by the endpoint;
idempotency key.

Partner app receives:

accepted quote state;
transfer reference or next action, depending on the API response.

If quote expired

If the API returns quote.expired:

do not retry acceptance with the same quote;
create or fetch a new quote;
show the customer the updated pricing;
ask the customer to accept the new quote.

---

9. Transfer submission flow

Use this flow after quote acceptance.

Quote accepted
  → Submit transfer
  → Read transfer state
  → Continue to confirmation or funding

Step 1 — Submit transfer

POST /v1/core/transfers/{transferId}/submit

Partner app sends:

transfer reference;
idempotency key;
any required confirmation payload defined by the API reference.

Partner app receives:

transfer status;
next step;
possible confirmation challenge;
possible funding webview information.

Step 2 — Read transfer detail

GET /v1/core/transfers/{transferId}

Use this to decide what screen to show next.

Common next actions:

customer confirmation required;
funding required;
transfer pending;
transfer held;
transfer completed;
cancellation available;
customer action required.

---

10. Device-bound confirmation flow

Use this flow when the transfer requires customer device confirmation.

Transfer requires confirmation
  → Fetch transfer detail
  → Build device assertion
  → Confirm transfer
  → Continue to funding or status polling

Step 1 — Read transfer detail

GET /v1/core/transfers/{transferId}

Partner app reads:

confirmation challenge;
challenge expiry;
transfer details to bind into the assertion.

Step 2 — Build device assertion

Partner app uses the registered device private key to sign the confirmation payload.

The private key must:

remain on the customer device;
not be sent to YesCash;
not be sent to partner servers.

Step 3 — Confirm transfer

POST /v1/core/transfers/{transferId}/confirm

Partner app sends:

device assertion JWS;
idempotency key.

Partner app receives:

confirmed transfer status;
funding webview URL if funding is required;
next step.

---

11. Funding webview flow

Use this flow when the API returns a funding webview URL.

API returns funding webview URL
  → App opens webview
  → Customer completes funding
  → App returns to transfer detail
  → Poll transfer status

Step 1 — Open funding webview

The partner app opens the returned funding URL.

The partner app must:

not collect payment instrument data itself unless explicitly supported by the API contract;
handle customer cancellation;
handle timeout;
handle return/deep-link;
continue by polling transfer detail.

Step 2 — Poll transfer detail

GET /v1/core/transfers/{transferId}

Poll until the transfer reaches a clear customer-facing state.

---

12. Transfer status polling flow

Use this flow after transfer creation, confirmation, funding, or cancellation.

Transfer action completed
  → Poll transfer detail
  → Show status and next action
  → Stop polling at terminal state

Detail endpoint

GET /v1/core/transfers/{transferId}

List endpoint

GET /v1/core/transfers

Use filters where supported:

status;
date range;
pagination cursor.

Partner app behavior

The partner app should:

show the customer the latest transfer state;
use nextStep or equivalent response fields where returned;
avoid aggressive polling;
stop polling when the transfer reaches a terminal state.

---

13. Cancellation flow

Use this flow when cancellation is available for the transfer.

Customer requests cancellation
  → App checks transfer detail
  → Submit cancellation
  → Poll transfer detail
  → Show cancellation result

Step 1 — Check transfer detail

GET /v1/core/transfers/{transferId}

Only show cancellation if the response indicates cancellation is available.

Step 2 — Submit cancellation

POST /v1/core/transfers/{transferId}/cancel

Partner app sends:

cancellation reason, if required;
idempotency key.

Step 3 — Poll transfer detail

GET /v1/core/transfers/{transferId}

Show final cancellation outcome when available.

---

14. Beneficiary archive flow

Use this flow when a customer removes or archives a beneficiary.

Customer selects beneficiary
  → Archive beneficiary
  → Refresh beneficiary list

Step 1 — Archive beneficiary

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

Step 2 — Refresh list

GET /v1/core/beneficiaries

Do not show archived beneficiaries as selectable for new transfers unless the API explicitly returns them as usable.

---

15. Standard happy path summary

1. POST /v1/auth/register/start
2. POST /v1/auth/register/verify-otp
3. Complete registration
4. POST /v1/auth/device-registration/start
5. POST /v1/auth/device-registration/complete
6. POST /v1/core/profile
7. POST /v1/core/kyc-sessions
8. Open KYC webview
9. GET /v1/core/kyc-sessions/{kycSessionId}
10. POST /v1/core/beneficiaries
11. Create signed quote
12. GET /v1/core/quotes/{quoteId}/disclosure
13. POST /v1/core/quotes/{quoteId}/accept
14. POST /v1/core/transfers/{transferId}/submit
15. POST /v1/core/transfers/{transferId}/confirm, if required
16. Open funding webview, if returned
17. GET /v1/core/transfers/{transferId}

---

16. Common recovery flows

Situation	Partner app action
Access token expired	Refresh token, then retry original request
Refresh token invalid	Send customer to login
Quote expired	Generate/fetch new quote and show updated pricing
KYC incomplete	Resume KYC flow
Device not registered	Start device registration
Device assertion failed	Retry once if safe; otherwise restart confirmation
Beneficiary not usable	Show returned remediation message
Transfer held	Show pending/review message and poll status
Funding cancelled	Return to transfer detail and show next available action
Cancellation pending	Poll transfer detail until outcome is available

---

17. Implementation checklist

Before moving to sandbox certification, confirm that the partner app can:

complete registration;
complete login;
refresh tokens;
clear tokens on logout;
register device keys;
submit profile data;
open and resume KYC webview;
create and list beneficiaries;
use signed quotes;
show disclosure before acceptance;
submit transfers;
perform device-bound confirmation;
open and resume funding webview;
poll transfer detail and list endpoints;
cancel eligible transfers;
handle common errors;
send correlation IDs;
send idempotency keys for retryable business actions.