YCMT EU Partner Developer — Getting Started Guide

Partner-facing integration starter guide | YCMT EU | v1.0

1. Purpose

This guide helps a partner development team start integrating a branded customer application with the YCMT EU white-label remittance platform.

It explains:

• What the partner application must build.
• Which YCMT APIs the partner application calls.
• What credentials and headers are required.
• The recommended integration sequence.
• How to complete the first sandbox calls.
• What must be tested before production activation.

This document is intentionally practical and partner-facing. It does not describe YCMT internal systems or internal compliance decisioning.

2. Integration model in one page

The partner application provides the branded customer experience. YCMT provides the regulated money transfer service behind that experience.

The partner application is responsible for:

• Presenting the user interface to the customer.
• Calling YCMT APIs using the documented request formats.
• Safely storing and forwarding customer access tokens.
• Displaying YCMT-provided statuses, errors, and remediation instructions.
• Guiding the customer through onboarding, KYC, beneficiary creation, quote review, transfer confirmation, funding, and status tracking.
• Handling sandbox testing and go-live readiness checks.

YCMT is responsible for:

• Customer authentication and token issuance.
• Customer identity and KYC decisions.
• Sanctions, AML, fraud, customer-status, and transaction controls.
• Quote acceptance validation.
• Transfer approval and execution.
• Funding, safeguarding, settlement, cancellation, refund, and reporting controls.

The partner must not attempt to bypass YCMT controls or create regulated actions outside the documented APIs.

3. What the partner application will integrate

The partner application integrates with three practical surfaces.

This Getting Started guide focuses on the first two surfaces. Quote signing and webhooks are covered in the separate Security and Signing Guide.

4. YCMT EU environments

YCMT provides separate environments for testing and production.

The sandbox URL above is a placeholder format. YCMT onboarding will provide the actual environment URLs.

Do not use production credentials in sandbox, and do not use sandbox credentials in production.

5. Credentials and access material

Before development starts, YCMT will issue the partner onboarding package.

The package normally includes:

Production credentials are issued only after YCMT approves the partner’s technical and operational readiness.

6. Common request headers

Every API request should include the headers required by the endpoint.

Typical headers:

Content-Type: application/json

Accept: application/json

X-Correlation-Id: <uuid-v4-generated-by-partner-app>

Ocp-Apim-Subscription-Key: <partner-api-key>

Customer-authenticated endpoints also require:

Authorization: Bearer <customer-access-token>

Idempotent write endpoints also require:

Idempotency-Key: <uuid-v4-generated-per-business-action>

Header rules

• Generate a new X-Correlation-Id for each logical customer action or request chain.
• Reuse the same Idempotency-Key only when retrying the same business action.
• Never log full access tokens, refresh tokens, OTPs, passwords, private keys, or device signing material.
• Always send JSON unless an endpoint explicitly says otherwise.

7. Recommended integration sequence

Build the integration in this order.

Do not start production activation before completing the sandbox and go-live checklist.

8. Customer journey overview

A typical new-customer journey is:

1. Customer opens partner app

2. Customer registers or logs in

3. Partner app receives customer tokens

4. Customer completes profile

5. Customer completes KYC

6. Customer registers device if required

7. Customer creates or selects beneficiary

8. Customer reviews quote and disclosure

9. Customer accepts quote

10. Customer submits and confirms transfer

11. Customer completes funding flow

12. Partner app polls transfer status and shows updates

The partner application must not create shortcuts around YCMT-controlled onboarding, KYC, quote acceptance, transfer confirmation, or funding steps.

9. First sandbox call — health check

Use the health endpoint to confirm that the base URL, network access, and API key are configured.

Example:

GET /v1/auth/health HTTP/1.1

Host: sandbox.api.eu.yescash.example

Accept: application/json

X-Correlation-Id: 2c3eb391-57e1-4312-a59d-85f9df38cf62

Ocp-Apim-Subscription-Key: <sandbox-api-key>

Example response:

{

"status": "ok",

"service": "YCMT Authentication API",

"timestamp": "2026-05-12T10:15:00Z"

}

If this call fails, check:

• Base URL.
• API key.
• Network allow-listing, if applicable.
• TLS certificate validation.
• Request headers.

10. First customer login flow

The login flow is two-step.

POST /v1/auth/start

POST /v1/auth/login

Step 1 — start login

The partner app sends the customer’s login identifier.

POST /v1/auth/start HTTP/1.1

Host: sandbox.api.eu.yescash.example

Content-Type: application/json

Accept: application/json

X-Correlation-Id: 93f0f2a3-9d4f-43c7-a3c6-9d02c4a65f2a

Ocp-Apim-Subscription-Key: <sandbox-api-key>

{

"identifier": "alice.martinez@example.com"

}

Example response:

{

"loginAttemptId": "lat_01HXAMPLELOGINATTEMPT",

"nextStep": "PASSWORD_REQUIRED"

}

Step 2 — complete login

POST /v1/auth/login HTTP/1.1

Host: sandbox.api.eu.yescash.example

Content-Type: application/json

Accept: application/json

X-Correlation-Id: 93f0f2a3-9d4f-43c7-a3c6-9d02c4a65f2a

Ocp-Apim-Subscription-Key: <sandbox-api-key>

{

"loginAttemptId": "lat_01HXAMPLELOGINATTEMPT",

"password": "<customer-password>"

}

Example response:

{

"accessToken": "<access-token>",

"refreshToken": "<refresh-token>",

"tokenType": "Bearer",

"expiresIn": 3600,

"subscriptionId": "sub_01HXAMPLECUSTOMER",

"nextStep": "CONTINUE"

}

The partner app must store tokens according to the security requirements. The subscriptionId is the partner-facing customer reference.

11. First profile read

After login, call the profile endpoint using the access token.

GET /v1/core/profile HTTP/1.1

Host: sandbox.api.eu.yescash.example

Accept: application/json

Authorization: Bearer <access-token>

X-Correlation-Id: b4a333e7-3881-40de-bfe7-44c98b7cfcde

Ocp-Apim-Subscription-Key: <sandbox-api-key>

Example response:

{

"subscriptionId": "sub_01HXAMPLECUSTOMER",

"customerStatus": "PENDING",

"kycStatus": "NOT_STARTED",

"profile": {

"firstName": null,

"lastName": null,

"dateOfBirth": null,

"email": "alice.martinez@example.com",

"phone": null

},

"nextStep": "COMPLETE_PROFILE"

}

The partner app should use customerStatus, kycStatus, and nextStep to guide the customer.

12. First profile submission

POST /v1/core/profile HTTP/1.1

Host: sandbox.api.eu.yescash.example

Content-Type: application/json

Accept: application/json

Authorization: Bearer <access-token>

X-Correlation-Id: e91c7dbf-3f63-47bb-b6bc-826f4693d1cf

Idempotency-Key: e84c830f-a1d0-4e73-b1bd-f2e54160b22c

Ocp-Apim-Subscription-Key: <sandbox-api-key>

{

"firstName": "Alice",

"lastName": "Martinez",

"dateOfBirth": "1990-04-18",

"nationality": "ES",

"residentialAddress": {

"line1": "Calle Mayor 10",

"city": "Madrid",

"postalCode": "28013",

"country": "ES"

}

}

Example response:

{

"subscriptionId": "sub_01HXAMPLECUSTOMER",

"customerStatus": "PENDING",

"kycStatus": "PROFILE_SUBMITTED",

"nextStep": "START_KYC"

}

13. First KYC session

Start a KYC session when the customer is ready to complete identity verification.

POST /v1/core/kyc-sessions HTTP/1.1

Host: sandbox.api.eu.yescash.example

Content-Type: application/json

Accept: application/json

Authorization: Bearer <access-token>

X-Correlation-Id: 1d8a595e-9f17-4c2f-a7ab-237d1543ef71

Idempotency-Key: 04a54677-78fb-46bb-92e0-2fcf88dfae10

Ocp-Apim-Subscription-Key: <sandbox-api-key>

{

"returnUrl": "https://partner.example/app/kyc/return",

"locale": "en"

}

Example response:

{

"kycSessionId": "kyc_01HXAMPLESSESSION",

"status": "STARTED",

"webviewUrl": "https://sandbox.verify.yescash.example/session/kyc_01HXAMPLESSESSION",

"expiresAt": "2026-05-12T10:45:00Z"

}

Open webviewUrl inside the partner app using the approved webview pattern. Do not collect identity documents outside the YCMT-approved flow.

14. First beneficiary creation

After the customer is eligible to proceed, create a beneficiary.

POST /v1/core/beneficiaries HTTP/1.1

Host: sandbox.api.eu.yescash.example

Content-Type: application/json

Accept: application/json

Authorization: Bearer <access-token>

X-Correlation-Id: f8a4ae66-83b3-4f58-b53a-a2bc80e395ab

Idempotency-Key: 61d84dd3-70c5-4fcb-a73c-071e5f9c482c

Ocp-Apim-Subscription-Key: <sandbox-api-key>

{

"firstName": "Carlos",

"lastName": "Rodriguez",

"country": "MA",

"payoutMethod": "BANK_ACCOUNT",

"bankAccount": {

"iban": "MA64011519000001205000534921"

}

}

Example response:

{

"beneficiaryId": "ben_01HXAMPLEBENEFICIARY",

"status": "ACTIVE",

"displayName": "Carlos Rodriguez",

"country": "MA",

"payoutMethod": "BANK_ACCOUNT"

}

15. First quote and disclosure flow

A typical quote flow is:

1. Partner presents available customer input fields.

2. Partner obtains or creates a quote according to its approved pricing model.

3. Partner app retrieves the quote and disclosure from YCMT.

4. Customer reviews the quote and disclosure.

5. Customer accepts before quote expiry.

Example quote retrieval:

GET /v1/core/quotes/quo_01HXAMPLEQUOTE HTTP/1.1

Host: sandbox.api.eu.yescash.example

Accept: application/json

Authorization: Bearer <access-token>

X-Correlation-Id: 4379807a-81da-4af9-8543-f80244e0ba31

Ocp-Apim-Subscription-Key: <sandbox-api-key>

Example response:

{

"quoteId": "quo_01HXAMPLEQUOTE",

"sendAmount": {

"amount": "100.000000",

"currency": "EUR"

},

"receiveAmount": {

"amount": "1085.000000",

"currency": "MAD"

},

"fee": {

"amount": "3.000000",

"currency": "EUR"

},

"exchangeRate": "10.850000",

"expiresAt": "2026-05-12T10:30:00Z",

"status": "AVAILABLE"

}

The customer must see the required disclosure before accepting the quote.

16. First transfer flow

A typical transfer flow is:

1. Customer accepts quote.

2. Customer submits transfer.

3. Customer confirms transfer if required.

4. Customer completes funding webview.

5. Partner app polls transfer status.

Example transfer status pull:

GET /v1/core/transfers/trf_01HXAMPLETRANSFER HTTP/1.1

Host: sandbox.api.eu.yescash.example

Accept: application/json

Authorization: Bearer <access-token>

X-Correlation-Id: 89d88ba8-e208-4931-bb5f-c1d16c05109f

Ocp-Apim-Subscription-Key: <sandbox-api-key>

Example response:

{

"transferId": "trf_01HXAMPLETRANSFER",

"status": "FUNDING",

"customerActionExpected": true,

"nextStep": "COMPLETE_FUNDING",

"funding": {

"fundingSessionId": "fds_01HXAMPLEFUNDING",

"webviewUrl": "https://sandbox.pay.yescash.example/session/fds_01HXAMPLEFUNDING"

}

}

The partner app should follow nextStep and customerActionExpected rather than guessing the next customer action.

17. Customer status basics

YCMT may return customer status information to help the partner app guide the customer.

Partner developers should treat customer status as an instruction for customer experience, not as an internal decision reason.

Do not display internal reason codes or speculate on AML, sanctions, fraud, or regulatory causes.

18. Error handling basics

YCMT APIs return structured errors. The partner app should use the returned code, hint, remediation, and correlation ID.

Example error response:

{

"error": {

"code": "auth.tokenExpired",

"message": "The session has expired.",

"hint": "hint.partner_app.token_refresh",

"remediation": "remediation.customer_ux.sign_in_again",

"correlationId": "cfb4ed22-43ac-4b29-b9e4-4e9ad874cbea"

}

}

Basic handling rules:

• For expired tokens, attempt refresh where permitted.
• For validation errors, correct the request before retrying.
• For idempotency conflicts, do not generate a new business action unless the customer explicitly restarts the action.
• For status-blocking errors, show only the approved customer-safe message.
• Always retain the correlationId for support escalation.

19. Logging and security basics

Partner applications must implement secure handling from the start.

Do:

• Use TLS for all API calls.
• Store tokens only in secure platform storage.
• Redact tokens, OTPs, passwords, private keys, and personal data from logs.
• Generate strong random UUIDs for correlation and idempotency keys.
• Protect signing keys if quote signing or webhook validation is implemented.
• Apply least-privilege access to backend systems.

Do not:

• Log full access or refresh tokens.
• Store customer passwords.
• Collect KYC documents outside approved YCMT flows.
• Modify transfer details after customer confirmation.
• Retry non-idempotent actions with a new idempotency key unless the customer restarts the action.
• Display internal speculation about compliance or risk decisions.

20. Sandbox testing checklist

Before requesting production activation, the partner must complete YCMT sandbox testing.

Minimum scenarios:

YCMT may require evidence of completed scenarios before production credentials are issued.

21. Go-live readiness checklist

A partner development team is ready for production activation only when:

• Sandbox tests are completed.
• Error handling is implemented.
• Token refresh and logout are implemented.
• Idempotency keys are implemented for required write actions.
• Correlation IDs are generated and retained for support.
• Customer-safe remediation messages are implemented.
• KYC and funding webviews are implemented using the approved pattern.
• Sensitive data redaction is verified.
• Production URLs and credentials are stored securely.
• Partner operations and support teams know the escalation process.
• YCMT has approved the technical go-live checklist.

22. Escalation and support

When escalating to YCMT support, include:

• Environment: sandbox or production.
• Partner application identifier.
• Endpoint called.
• Timestamp in UTC.
• X-Correlation-Id.
• Error code, if any.
• Sanitised request/response sample.
• Customer-facing impact.

Do not send:

• Full access tokens.
• Refresh tokens.
• Passwords.
• OTPs.
• Private keys.
• Unredacted identity documents.
• Full card or bank credentials.

23. Related partner developer documents

This Getting Started guide is the entry point. The full partner developer pack also includes:

60_YCMT_EU_PartnerDev_API_Guide_v1_0.md

60_YCMT_EU_PartnerDev_Flows_Guide_v1_0.md

60_YCMT_EU_PartnerDev_Errors_Statuses_And_Retry_Guide_v1_0.md

60_YCMT_EU_PartnerDev_Security_And_Signing_Guide_v1_0.md

60_YCMT_EU_PartnerDev_Sandbox_And_GoLive_Guide_v1_0.md

60_YCMT_EU_PartnerDev_OpenAPI_And_Postman_Pack/

24. Final integration rule

The partner application must use the YCMT APIs exactly as documented. Any customer registration, KYC, quote acceptance, transfer creation, confirmation, funding, cancellation, or refund action must go through the YCMT-controlled API and customer-authorised flow.