YCMT EU Partner Developer
Security and Signing Guide
Partner developer integration pack | Version 1.0 | YCMT EU
| Partner-safe scope
This guide explains the security and signing responsibilities a partner developer must implement when integrating with the YCMT EU APIs. It deliberately avoids YCMT internal system details. The partner app only needs to follow the documented API, token, signing, webhook, and operational security requirements. |
|---|
| Field | Value |
|---|
| Document | 60_YCMT_EU_PartnerDev_Security_And_Signing_Guide_v1_0.docx |
| Audience | Partner application developers, partner backend developers, partner DevOps/security teams |
| Perimeter | YCMT EU only |
| Status | Draft for partner onboarding use |
| Confidentiality | Partner-facing under onboarding/NDA controls |
| Related pack files | Getting Started; API Guide; Flows Guide; Errors, Statuses and Retry Guide; Sandbox and Go-Live Guide; OpenAPI and Postman Pack |
Contents
- 1. Purpose and integration boundary
- 2. Security responsibilities at a glance
- 3. API credentials and environment separation
- 4. Customer access token handling
- 5. Secure request construction
- 6. Device registration and transfer confirmation
- 7. Quote signing for partner pricing engines
- 8. Webhook verification
- 9. Key rotation and credential lifecycle
- 10. Logging and data protection rules
- 11. Incident handling and escalation
- 12. Implementation checklist
1. Purpose and integration boundary
This document tells partner developers what security controls must be implemented in the partner application and partner backend when integrating with the YCMT EU APIs. It is practical by design: it explains what to send, what to store, what to sign, what to verify, and what must never be logged or exposed.
The partner app presents a branded customer experience. YCMT validates the customer, partner, compliance, transaction, funding, and settlement controls before any regulated action proceeds. The partner must not try to reproduce, bypass, or override those controls.
| Topic | Partner responsibility | YCMT responsibility |
|---|
| Customer access token | Store securely, send on API calls, refresh before expiry where supported. | Validate token and enforce customer, partner, and transaction controls. |
| Device confirmation | Generate and protect device private key; sign confirmation payload when required. | Validate device proof and decide whether transfer may proceed. |
| Quote signing | If operating a pricing engine, sign quotes exactly as specified and protect signing keys. | Validate quote signature and enforce pricing/disclosure controls. |
| Webhooks | Expose secure webhook endpoint, verify YCMT delivery, process idempotently. | Send partner notifications and provide retry/replay according to the integration contract. |
| Incidents | Notify YCMT quickly of credential, key, device, webhook, or customer-data exposure. | Assess regulated impact and instruct required containment steps. |
| Non-negotiable boundary
The partner application may request API actions on behalf of an authenticated customer, but it cannot decide KYC outcomes, AML outcomes, sanctions outcomes, transfer approval, release, cancellation success, refund execution, or settlement completion. |
|---|
2. Security responsibilities at a glance
| Area | Required partner behaviour |
|---|
| Transport security | Use HTTPS for every API and webhook call. Do not allow downgrade, insecure redirects, or mixed content. |
| Credential storage | Store API keys, signing keys, webhook secrets, and environment credentials in a secure secrets manager. Never hard-code them in mobile apps or public repositories. |
| Customer tokens | Treat access and refresh tokens as sensitive credentials. Store them using platform-secure storage and never log them. |
| Private keys | Keep private signing keys and device private keys private. Public keys may be shared only through the documented onboarding or registration process. |
| Data minimisation | Only collect and retain the information required by the documented integration. Do not create parallel regulated records. |
| Idempotency | Use idempotency keys for applicable POST operations to avoid duplicate business actions. |
| Webhook processing | Verify authenticity, reject stale/replayed events, process duplicate events safely. |
| Incident reporting | Report suspected exposure of tokens, keys, webhook secrets, production credentials, or customer data. |
3. API credentials and environment separation
YCMT issues separate credentials for sandbox and production. Sandbox credentials must never be used in production, and production credentials must never be used in sandbox or shared test tools outside the approved partner environment.
| Credential or asset | Used for | Storage rule |
|---|
| Partner API subscription credential | Identifies the partner application when calling YCMT APIs. | Backend secret store or approved mobile distribution method. Never place production credentials in source code. |
| Customer access token | Authorises customer-context API calls. | Secure storage on customer device; short-lived; never logged. |
| Customer refresh token | Obtains a fresh access token where supported. | Highest sensitivity. Store only in secure platform storage; clear on logout. |
| Partner quote-signing private key | Signs partner-generated quotes where the partner operates pricing. | Backend-only secret or HSM/KMS. Never store in a mobile app. |
| Webhook verification material | Verifies YCMT webhook delivery and prevents spoofing/replay. | Backend-only secret store. Rotate according to onboarding instructions. |
| Device private key | Signs customer device confirmation assertions. | Generated and stored on the customer device using OS secure key storage. Not exportable where platform supports it. |
3.1 Environment rules
- Keep separate base URLs, credentials, signing keys, webhook endpoints, and test data for sandbox and production.
- Do not copy production customer data into sandbox.
- Do not configure sandbox webhooks to production systems unless explicitly approved for a controlled test.
- Use production credentials only after YCMT confirms go-live approval.
4. Customer access token handling
The partner app sends the customer access token in the Authorization header for customer-context API calls. YCMT validates the token and applies the relevant customer, partner, compliance, and transaction controls server-side.
| Do | Do not |
|---|
| Store tokens in secure platform storage. | Do not store tokens in plain text, browser local storage for high-risk flows, logs, analytics, crash reports, or screenshots. |
| Send tokens only to YCMT API endpoints over HTTPS. | Do not send tokens to partner analytics, support, marketing, or third-party SDKs. |
| Refresh tokens only through the documented token refresh flow. | Do not create custom token refresh or token sharing mechanisms. |
| Clear local tokens on logout, account switch, device compromise, or customer request. | Do not keep old tokens after logout or app uninstall/reinstall recovery. |
| Treat token expiry as normal and guide the customer through re-login when required. | Do not interpret token contents to make authorisation or compliance decisions. |
Use the standard bearer-token format:
Authorization: Bearer <customer_access_token>
5. Secure request construction
| Control | Partner implementation requirement |
|---|
| HTTPS only | All calls must use HTTPS. Reject untrusted certificates and avoid debug overrides in production builds. |
| Correlation ID | Send a correlation ID where supported so support teams can trace requests without exposing customer secrets. |
| Idempotency key | Send a unique idempotency key for applicable business actions such as submissions or acceptance flows. |
| Input validation | Validate basic client-side format, but rely on YCMT response codes for authoritative acceptance or rejection. |
| Clock handling | Ensure device clocks are reasonably accurate for token expiry and signing challenges. |
| No sensitive query strings | Do not place tokens, customer identifiers, document data, or secrets in URLs. |
6. Device registration and transfer confirmation
Some YCMT flows require confirmation from a registered customer device. The partner app is responsible for generating and protecting the device key and for producing the confirmation signature when prompted by the API.
6.1 Device registration overview
- The customer signs in or completes registration.
- The partner app starts device registration through the documented API endpoint.
- The app generates a device key pair using secure platform APIs.
- The app sends the public key and proof of possession to YCMT.
- YCMT registers the device if the proof is valid and the customer context is eligible.
| Device asset | Partner app rule |
|---|
| Device private key | Generated on the customer device. Must be protected by OS secure storage. Must not be exported, logged, synced to partner servers, or backed up insecurely. |
| Device public key | Sent to YCMT during registration. May be stored by the partner only for troubleshooting metadata if needed. |
| Device identifier | Treat as customer-related metadata. Do not use it for cross-service tracking. |
| Registration challenge | Use only for the current registration ceremony. Do not reuse. |
6.2 Transfer confirmation signing
When YCMT requires device-bound confirmation, the API provides or references the data that must be confirmed. The app must show the customer the material transfer details and sign the confirmation payload using the registered device private key.
| Requirement | Implementation guidance |
|---|
| Show transfer details before signing | Display the amount, currency, recipient, and other required details before the customer confirms. |
| Bind signature to the transaction | Sign exactly the documented confirmation payload. Do not sign an incomplete, altered, or partner-defined substitute payload. |
| Use current challenge/nonce only | Do not reuse old challenges, nonces, or signatures. |
| Handle failure safely | If signing fails, do not submit a transfer as confirmed. Prompt retry or escalate according to the error returned. |
7. Quote signing for partner pricing engines
This section applies only where the partner operates an approved pricing engine and is required to sign quotes. If YCMT provides pricing directly for the integration, this section is informational only.
| Quote-signing requirement | Partner implementation |
|---|
| Signing algorithm | Use the algorithm and key type specified in the onboarding materials and API contract. Do not change algorithms without YCMT approval. |
| Canonical payload | Sign the exact canonical quote payload. Field order, numeric format, and required fields must match the specification. |
| Private key custody | Keep the quote-signing private key in backend-controlled secure infrastructure. Never place it in web or mobile apps. |
| Key identification | Include the correct key identifier where required so YCMT can validate the signature. |
| Quote expiry | Respect quote expiry. Do not re-sign expired quotes as if they were still valid. Generate a new quote instead. |
| Customer binding | Bind quotes to the documented partner-facing customer reference where required. Never attempt to create quotes for another partner channel. |
| Pricing boundary
The partner may control brand and pricing strategy within the approved commercial envelope. YCMT still validates the quote, disclosure, customer eligibility, and transaction controls before execution. |
|---|
8. Webhook verification
Webhooks notify the partner backend about relevant events. The partner backend must verify webhook authenticity, reject replayed or stale deliveries, and process duplicate deliveries safely.
| Webhook control | Partner implementation requirement |
|---|
| Endpoint security | Expose only HTTPS webhook endpoints with valid certificates. |
| Authenticity verification | Verify the YCMT-provided signature or validation mechanism before trusting the event. |
| Replay protection | Use event ID, timestamp, nonce, or the specified replay controls to reject stale or duplicated malicious deliveries. |
| Idempotent processing | Store processed event IDs and make event handling safe to repeat. |
| Acknowledgement | Return the documented success response only after the event has been accepted for processing. |
| Retries | Expect retry delivery. Do not treat duplicate webhook receipt as a new business event. |
| Data minimisation | Store only event fields required for customer support, reconciliation, and operational follow-up. |
8.1 Webhook event handling pattern
- Receive event over HTTPS.
- Validate signature or verification material.
- Check replay window and event ID.
- Check whether event has already been processed.
- Apply event to partner system state or enqueue for processing.
- Return success response.
- Escalate unexpected or unverifiable events to YCMT support/security contact.
9. Key rotation and credential lifecycle
| Asset | Rotation trigger | Partner action |
|---|
| API credentials | Scheduled rotation, suspected exposure, employee/vendor access change. | Request or accept new credential, deploy, verify, remove old credential. |
| Quote-signing keys | Scheduled rotation, suspected private-key compromise, algorithm/key-size upgrade. | Generate new key pair, register public key with YCMT, sign with new key after activation, retire old key after overlap window. |
| Webhook verification material | Scheduled rotation or suspected exposure. | Configure new verification material, support overlap if specified, monitor delivery success. |
| Device key | New device, lost device, suspected compromise. | Run device re-registration or recovery flow. Do not copy old private key to a new device. |
| Postman/test credentials | Team changes, shared environment cleanup, sandbox reset. | Rotate and redistribute securely. Do not use shared personal accounts for production. |
| Emergency rotation
For suspected exposure of production credentials, private keys, webhook secrets, or customer tokens, treat the event as urgent. Contain locally, stop further exposure, and notify YCMT through the incident contact route in the partner onboarding materials. |
|---|
10. Logging and data protection rules
Partner systems should log enough to troubleshoot integration issues, but must not log secrets, sensitive customer data, or regulated decision details.
| Safe to log | Do not log |
|---|
| Correlation ID | Access tokens, refresh tokens, OTPs, passwords, private keys, webhook secrets. |
| Endpoint name and HTTP status | Full Authorization headers or full request/response bodies containing personal data. |
| Partner-facing resource IDs where necessary for support | Identity documents, KYC images, bank details beyond masked display, full card/payment instrument data. |
| Error code and remediation identifier | Internal speculation about AML, sanctions, fraud, or compliance reasons. |
| Timestamp, environment, app version | Customer credentials, device private key material, signing payload secrets. |
- Mask customer identifiers wherever possible.
- Use separate log retention rules for sandbox and production.
- Restrict production log access to authorised personnel only.
- Remove sensitive headers and payloads from crash reports and analytics tools.
- Do not send YCMT API responses containing personal data to third-party analytics without approval.
11. Incident handling and escalation
| Incident type | Examples | Immediate partner action |
|---|
| Credential exposure | API credential, quote-signing key, webhook secret, production environment file leaked. | Revoke or contain locally where possible; notify YCMT; prepare affected asset list and timestamps. |
| Token exposure | Customer tokens found in logs, analytics, screenshots, support tickets. | Stop logging source; isolate records; notify YCMT with affected customer/time range if known. |
| Device compromise | Customer reports lost/stolen device or suspected malware. | Guide customer through approved recovery/escalation path; do not manually bypass confirmation. |
| Webhook spoofing or replay | Unexpected events, failed verification, repeated stale events. | Reject events; preserve samples; notify YCMT. |
| Customer data leak | Personal data exported to wrong system or recipient. | Contain, preserve evidence, notify YCMT and follow agreed data incident process. |
| Production outage | Partner app cannot reach YCMT APIs or webhook processing is down. | Activate partner incident process; inform YCMT; avoid misleading customer messaging. |
- Partner name and environment: sandbox or production.
- Incident type and first detected time.
- Affected credentials, endpoints, customers, events, or systems if known.
- Containment steps already taken.
- Relevant correlation IDs, event IDs, timestamps, and app versions.
- Whether customer data or regulated transaction data may be affected.
12. Implementation checklist
| # | Checkpoint | Done |
|---|
| 1 | Sandbox and production credentials stored separately and securely. | |
| 2 | Customer tokens are stored securely and never logged. | |
| 3 | Authorization header is sent only to YCMT API endpoints over HTTPS. | |
| 4 | Idempotency keys are implemented for applicable business actions. | |
| 5 | Device key generation uses secure platform APIs and private key is not exportable where supported. | |
| 6 | Transfer confirmation signs the documented payload only after showing customer the material details. | |
| 7 | Quote signing implemented only on backend infrastructure, not in the customer app. | |
| 8 | Webhook verification, replay protection, and idempotent processing are implemented. | |
| 9 | Logs mask or exclude tokens, secrets, credentials, private keys, OTPs, and sensitive personal data. | |
| 10 | Credential/key rotation process is documented and tested. | |
| 11 | Incident contact route is configured and known to engineering and operations teams. | |
| 12 | Security tests completed before go-live. | |
Appendix A — Partner developer do / do not summary
| Do | Do not |
|---|
| Use YCMT APIs exactly as documented. | Do not call undocumented endpoints or attempt to bypass customer authentication. |
| Protect credentials, tokens, and private keys. | Do not share credentials between environments or teams without controls. |
| Verify webhooks before processing. | Do not trust webhook payloads without verification. |
| Handle retry and duplicate delivery safely. | Do not create duplicate transfers or customer actions on retry. |
| Escalate security concerns quickly. | Do not wait for full internal investigation before notifying YCMT of serious exposure. |
Appendix B — Partner-safe terminology
| Term | Meaning for partner developers |
|---|
| YCMT EU | The licensed Yes Cash Money Transfer service for the EU perimeter. |
| Customer access token | Credential issued to the customer session and sent by the partner app to call customer-context APIs. |
| subscriptionId | Partner-facing customer reference returned by YCMT for the customer relationship in the partner channel. |
| Device registration | Process by which the customer device registers a public key for later transfer confirmation. |
| Device confirmation | Customer-device signature used to confirm a sensitive transfer action. |
| Quote signature | Partner-generated signature on a quote where the partner operates an approved pricing engine. |
| Webhook | Server-to-server notification sent by YCMT to the partner backend. |