Core API Guide

Version: v1.0 draft

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

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

---

1. Purpose

This guide explains how to use the Core API for customer profile, KYC, beneficiaries, quotes, transfers, funding, cancellation, and transfer status.

The Core API is exposed under:

https://api.yes.cash/v1/core

Every Core API call requires a customer access token obtained from the Authentication API.

---

2. Core API model

The Core API is customer-authenticated.

The partner app must call the Core API on behalf of the logged-in customer using:

Authorization: Bearer <accessToken>

Basic model:

Customer logs in
  -> Partner app receives accessToken
  -> Partner app calls /v1/core/... with the accessToken
  -> API returns customer-specific profile, beneficiary, quote, or transfer data

Do not send customer identifiers in Core API URLs. The customer context is resolved from the access token.

---

3. Required headers

Use these headers for Core API calls:

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

For POST operations that create or advance a business action, also send:

Idempotency-Key: <uuid-v4>

Use one idempotency key per business action. Reuse the same key only when retrying the same action after a timeout or network failure.

---

4. Standard customer journey

A typical integration uses the Core API in this order:

GET/POST profile
  -> create KYC session
  -> create beneficiary
  -> create quote
  -> get disclosure
  -> accept quote
  -> submit transfer
  -> confirm transfer if required
  -> open funding webview if returned
  -> poll transfer status

Some steps may be skipped depending on the customer status, transfer amount, beneficiary state, or API response.

---

5. Profile

5.1 Submit customer profile

Endpoint:

POST https://api.yes.cash/v1/core/profile

Use this endpoint after registration when the customer must complete identity information.

Example request:

{
  "firstName": "Aicha",
  "lastName": "El Amrani",
  "dateOfBirth": "1990-03-15",
  "nationality": "MAR",
  "residenceCountry": "ESP",
  "residenceAddress": {
    "line1": "Calle Mayor 10",
    "city": "Madrid",
    "postalCode": "28013",
    "country": "ESP"
  }
}

Partner-app behavior:

• collect the required identity fields;
• submit the profile before allowing transfer initiation;
• show validation errors beside the relevant fields;
• call GET /v1/core/profile after submission to refresh customer state.

5.2 Read customer profile

Endpoint:

GET https://api.yes.cash/v1/core/profile

Use this endpoint to display the customer profile and operational state.

Typical response fields include:

{
  "subscriptionId": "SUB-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "customerStatus": "PENDING",
  "kycStatus": "NOT_STARTED",
  "firstName": "Aicha",
  "lastName": "El Amrani",
  "identifiers": [
    {
      "type": "EMAIL",
      "value": "aicha@example.com",
      "verified": true
    }
  ]
}

Partner-app behavior:

• use customerStatus and kycStatus to decide the next screen;
• use subscriptionId only as a partner-side reference key;
• do not ask the customer to re-enter profile data if the profile is already complete.

---

6. KYC sessions

6.1 Create KYC session

Endpoint:

POST https://api.yes.cash/v1/core/kyc-sessions

Use this endpoint to start a customer verification session.

Example response:

{
  "kycSessionId": "KYC-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "status": "CREATED",
  "kycWebviewUrl": "https://api.yes.cash/webviews/kyc/KYC-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "expiresAt": "2026-05-11T15:30:00Z"
}

Partner-app behavior:

• open kycWebviewUrl inside the approved app webview or browser flow;
• do not collect document images directly in the partner app unless separately approved;
• after the customer exits the webview, poll the KYC session or profile endpoint.

6.2 Read KYC session

Endpoint:

GET https://api.yes.cash/v1/core/kyc-sessions/{kycSessionId}

Use this endpoint to check whether the KYC session is still pending, completed, expired, or failed.

Partner-app behavior:

• poll only at reasonable intervals;
• stop polling after a terminal session state;
• if the session expires, create a new KYC session.

---

7. Beneficiaries

7.1 List beneficiaries

Endpoint:

GET https://api.yes.cash/v1/core/beneficiaries

Use this endpoint to show the customer their saved beneficiaries.

7.2 Create beneficiary

Endpoint:

POST https://api.yes.cash/v1/core/beneficiaries

Example request:

{
  "firstName": "Karim",
  "lastName": "El Amrani",
  "dateOfBirth": "1988-04-20",
  "nationality": "MA",
  "countryOfResidence": "MA",
  "relationshipToCustomer": "FAMILY"
}

Important behavior:

• beneficiary creation may return before screening is complete;
• the beneficiary may not be immediately usable for transfers;
• destination account, wallet, or payout details are normally collected at transfer submission, not at beneficiary creation.

7.3 Read beneficiary

Endpoint:

GET https://api.yes.cash/v1/core/beneficiaries/{beneficiaryId}

Use this endpoint to refresh beneficiary state before quote or transfer submission.

7.4 Archive beneficiary

Endpoint:

POST https://api.yes.cash/v1/core/beneficiaries/{beneficiaryId}/archive

Use this endpoint when the customer removes a beneficiary from their list.

Partner-app behavior:

• treat archive as a customer action;
• do not show archived beneficiaries as selectable for new transfers;
• keep local UI state in sync after archive succeeds.

---

8. Quotes

8.1 Create quote

Endpoint:

POST https://api.yes.cash/v1/core/quotes

Use this endpoint to create a quote for a selected beneficiary and amount.

Example request:

{
  "originAmount": "100.000000",
  "originCurrency": "EUR",
  "destinationCurrency": "MAD",
  "beneficiaryId": "BEN-01HX9F2J7K3M5N7P9Q1R3T5V7W"
}

Partner-app behavior:

• show the returned quote to the customer;
• respect the quote expiry time;
• do not allow acceptance after expiry;
• if the quote expires, create a new quote.

8.2 Fetch quote

Endpoint:

GET https://api.yes.cash/v1/core/quotes/{quoteId}

Use this endpoint to refresh quote details before disclosure or acceptance.

8.3 Fetch quote disclosure

Endpoint:

GET https://api.yes.cash/v1/core/quotes/{quoteId}/disclosure

Use this endpoint before quote acceptance.

Example response:

{
  "quoteId": "QTE-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "disclosureToken": "DT-01HXBL2S3T5V7X9Z1A3C5E7G9I",
  "originAmount": "100.000000",
  "originCurrency": "EUR",
  "destinationAmount": "1085.000000",
  "destinationCurrency": "MAD",
  "fees": "3.000000",
  "rate": "10.850000",
  "expiresAt": "2026-05-11T15:00:00Z"
}

Partner-app behavior:

• show the disclosure before the customer accepts;
• preserve the returned disclosureToken for acceptance;
• do not modify quoted amounts, fees, rate, or expiry in the UI.

8.4 Accept quote

Endpoint:

POST https://api.yes.cash/v1/core/quotes/{quoteId}/accept

Example request:

{
  "disclosureToken": "DT-01HXBL2S3T5V7X9Z1A3C5E7G9I",
  "purposeOfTransfer": "FAMILY_SUPPORT"
}

Example response:

{
  "quoteId": "QTE-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "transferId": "TRF-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "transferStatus": "REGISTERED"
}

Partner-app behavior:

• use the returned transferId for the next transfer step;
• do not re-use a disclosure token after successful acceptance;
• if acceptance fails because the quote expired, restart from quote creation.

---

9. Transfers

9.1 Submit transfer

Endpoint:

POST https://api.yes.cash/v1/core/transfers/{transferId}/submit

Use this endpoint to attach the selected beneficiary, payout method, and purpose to the transfer.

Example request:

{
  "beneficiaryId": "BEN-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "payoutMethod": {
    "type": "BANK_ACCOUNT",
    "country": "MA",
    "currency": "MAD",
    "accountNumber": "012345678901234567890123"
  },
  "purposeOfTransfer": "FAMILY_SUPPORT"
}

Example response:

{
  "transferId": "TRF-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "transferStatus": "VALIDATING",
  "customerActionExpected": false,
  "nextStep": "WAIT_FOR_VALIDATION"
}

Partner-app behavior:

• submit only after quote acceptance;
• handle asynchronous validation states;
• call GET /v1/core/transfers/{transferId} to determine the next action.

9.2 Confirm transfer

Endpoint:

POST https://api.yes.cash/v1/core/transfers/{transferId}/confirm

Use this endpoint when the transfer detail response says device confirmation is required.

Request body:

{
  "deviceAssertion": "<jws-compact-serialization>"
}

Partner-app behavior:

• generate the device assertion on the registered customer device;
• use RS256 for the assertion;
• include the current confirmation challenge inside the signed assertion;
• do not confirm a transfer if the challenge has expired.

The detailed signing process is covered in 08_Device_Bound_Authentication.md.

9.3 Funding webview

After confirmation, the API may return a fundingWebviewUrl.

Example:

{
  "transferId": "TRF-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "transferStatus": "FUNDING",
  "fundingSessionId": "FND-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "fundingWebviewUrl": "https://api.yes.cash/webviews/funding/FND-01HX9F2J7K3M5N7P9Q1R3T5V7W"
}

Partner-app behavior:

• open the funding webview URL for the customer;
• do not collect card, bank, or payment credentials directly unless separately approved;
• after the webview closes, poll the transfer detail endpoint.

9.4 Read transfer detail

Endpoint:

GET https://api.yes.cash/v1/core/transfers/{transferId}

Use this endpoint to display the latest transfer state and next action.

Example response:

{
  "transferId": "TRF-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "transferStatus": "VALIDATED",
  "customerActionExpected": true,
  "nextStep": "CONFIRM_TRANSFER",
  "confirmationChallenge": "CHL-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "confirmationChallengeExpiresAt": "2026-05-11T15:05:00Z"
}

Partner-app behavior:

• use nextStep to drive the UI;
• when confirmationChallenge is present, ask the device layer to sign it;
• refresh the transfer detail if the challenge expires.

9.5 List transfers

Endpoint:

GET https://api.yes.cash/v1/core/transfers

Common query parameters may include state, date filters, and pagination cursor depending on the API reference.

Partner-app behavior:

• use this endpoint for transfer history;
• paginate rather than loading all transfers;
• use transfer detail for full state-specific information.

9.6 Cancel transfer

Endpoint:

POST https://api.yes.cash/v1/core/transfers/{transferId}/cancel

Example request:

{
  "cancellationReason": "CUSTOMER_REQUEST"
}

Possible responses:

• 200 OK when cancellation is completed immediately;
• 202 Accepted when cancellation requires asynchronous processing;
• 409 Conflict when the transfer is no longer cancellable.

Partner-app behavior:

• allow cancellation only when the transfer detail indicates cancellation is available;
• after a 202 Accepted, continue polling transfer detail;
• show the final cancellation outcome when available.

---

10. Customer statuses and Core API behavior

The partner app should use customerStatus from the profile or relevant responses to decide the user journey.

Do not infer hidden reasons from a status. Display only the message, hint, or remediation returned by the API.

---

11. Common error handling

Use the standard error envelope returned by the API.

Typical error categories:

Do not pattern-match on human-readable messages. Use the stable error code, hint, and remediation fields.

---

12. Implementation checklist

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

• call GET /v1/core/profile with a valid access token;
• submit a complete profile;
• create and track a KYC session;
• create and list beneficiaries;
• create a quote;
• fetch disclosure before quote acceptance;
• accept a quote and store the returned transferId;
• submit transfer details;
• handle validation and pending states;
• generate device confirmation when required;
• open funding webview URLs;
• poll transfer detail until terminal state;
• cancel a cancellable transfer;
• handle expired token and quote-expired errors;
• send X-Correlation-Id on every request;
• send Idempotency-Key on mutating business actions.

---

13. Related package files

Use these files with this guide:

02_Authentication_Guide.md
04_End_to_End_Flows.md
05_Headers_Idempotency_Errors.md
08_Device_Bound_Authentication.md
09_Webviews_Guide.md
10_Customer_Status_and_UX_Guide.md
api-reference/core.openapi.yaml