Sandbox and Testing Guide

This guide explains how partner technical teams should test their integration before production launch.

Use this host in API examples:

https://api.yes.cash

Sandbox credentials, test customer identifiers, and test payment details are issued separately during partner onboarding.

---

1. Purpose

The sandbox lets partner teams validate:

• authentication;
• customer registration;
• token refresh;
• device registration;
• profile and KYC flow;
• beneficiary creation;
• quote signing;
• quote acceptance;
• transfer submission;
• device-bound confirmation;
• funding webview handling;
• transfer status polling;
• cancellation;
• error handling;
• idempotent retries.

---

2. Sandbox materials

The partner onboarding team should provide:

---

3. Base request setup

Every sandbox request should include:

Ocp-Apim-Subscription-Key: <sandbox-subscription-key>
X-Correlation-Id: <uuid>

For authenticated calls:

Authorization: Bearer <access-token>

For idempotent business actions:

Idempotency-Key: <uuid>

---

4. Recommended test order

Run tests in this order:

1. Connectivity
2. Registration
3. Login
4. Token refresh
5. Device registration
6. Profile submission
7. KYC session
8. Beneficiary creation
9. Quote signing
10. Quote disclosure
11. Quote acceptance
12. Transfer submission
13. Device confirmation
14. Funding webview
15. Transfer status polling
16. Cancellation
17. Error handling
18. Idempotency
19. Logging and support traceability

---

5. Connectivity test

Goal

Confirm the partner can reach the API and receive a valid response.

Test

Call the agreed health or first available API endpoint.

Example:

GET https://api.yes.cash/v1/auth/health
Ocp-Apim-Subscription-Key: <sandbox-subscription-key>
X-Correlation-Id: <uuid>

Expected result

• HTTP response is returned.
• Response includes a correlation ID.
• No TLS or network error occurs.

---

6. Registration test

Goal

Create a new customer session from the partner app.

Steps

1. POST /v1/auth/register/start
2. POST /v1/auth/register/verify-otp
3. Complete registration
4. Store access token and refresh token securely

Expected result

• registration flow completes;
• access token is returned;
• refresh token is returned;
• customer can call GET /v1/core/profile.

---

7. Login test

Goal

Confirm an existing customer can sign in.

Steps

1. POST /v1/auth/start
2. POST /v1/auth/login
3. GET /v1/core/profile

Expected result

• login succeeds;
• access token is returned;
• profile call succeeds.

---

8. Token refresh test

Goal

Confirm token refresh works and expired access tokens are handled.

Steps

1. Login
2. Call POST /v1/auth/refresh
3. Use new access token
4. Call GET /v1/core/profile

Expected result

• refresh succeeds;
• new access token works;
• original session remains usable according to API response.

Negative test

Use an invalid refresh token.

Expected app behavior:

• clear local session;
• send customer to login;
• do not loop refresh attempts.

---

9. Logout test

Goal

Confirm customer logout is handled safely.

Steps

1. Login
2. POST /v1/auth/logout
3. Clear local tokens
4. Attempt authenticated call

Expected result

• logout call succeeds where token is valid;
• app clears access and refresh tokens;
• customer must log in again.

---

10. Device registration test

Goal

Register a customer device for transfer confirmation.

Steps

1. Login
2. POST /v1/auth/device-registration/start
3. Generate RSA device key
4. Build registration proof JWS
5. POST /v1/auth/device-registration/complete

Expected result

• device registration succeeds;
• API returns active device state;
• app stores local device registration state;
• private key never leaves device.

Negative tests

---

11. Profile submission test

Goal

Submit customer profile data required for transfer eligibility.

Steps

1. GET /v1/core/profile
2. POST /v1/core/profile
3. GET /v1/core/profile

Expected result

• missing fields are accepted when valid;
• profile state updates;
• validation errors are handled clearly.

Negative tests

---

12. KYC session test

Goal

Confirm KYC webview can be opened and status can be read after return.

Steps

1. POST /v1/core/kyc-sessions
2. Open returned KYC webview URL
3. Complete or simulate KYC
4. GET /v1/core/kyc-sessions/{kycSessionId}
5. GET /v1/core/profile

Expected result

• KYC webview opens;
• app resumes after webview;
• KYC status is fetched from API;
• app shows the correct next action.

Negative tests

---

13. Beneficiary creation test

Goal

Create and read a beneficiary.

Steps

1. POST /v1/core/beneficiaries
2. GET /v1/core/beneficiaries
3. GET /v1/core/beneficiaries/{beneficiaryId}

Expected result

• beneficiary is created;
• list endpoint includes the beneficiary;
• detail endpoint returns masked payout details;
• unusable beneficiary states are handled safely.

Negative tests

---

14. Quote signing test

Goal

Confirm partner-generated signed quotes verify correctly.

Steps

1. Build quote payload
2. Canonicalise using JCS
3. Sign with RS256
4. Confirm JWS verifies locally
5. Use quote in quote/disclosure/acceptance flow

Expected result

• quote signing succeeds locally;
• API accepts the signed quote where applicable;
• expired quotes are rejected and handled by app.

Negative tests

---

15. Quote disclosure and acceptance test

Goal

Confirm the customer sees disclosure before quote acceptance.

Steps

1. GET /v1/core/quotes/{quoteId}
2. GET /v1/core/quotes/{quoteId}/disclosure
3. Show disclosure to customer
4. POST /v1/core/quotes/{quoteId}/accept

Expected result

• disclosure is displayed;
• customer confirms;
• quote acceptance succeeds;
• app stores returned transfer reference or next step.

Negative test

Use an expired quote.

Expected app behavior:

• stop acceptance flow;
• generate/fetch a new quote;
• show updated pricing;
• ask customer to accept again.

---

16. Transfer submission test

Goal

Submit a transfer after quote acceptance.

Steps

1. POST /v1/core/transfers/{transferId}/submit
2. GET /v1/core/transfers/{transferId}

Expected result

• transfer is submitted;
• API returns current transfer state;
• app follows returned next step;
• idempotency key is used.

Retry test

Submit request and simulate timeout, then retry with the same Idempotency-Key.

Expected result:

• API does not create duplicate business action;
• app receives final or current state.

---

17. Device confirmation test

Goal

Confirm a transfer using registered device key.

Steps

1. GET /v1/core/transfers/{transferId}
2. Read confirmation challenge
3. Build device assertion payload
4. Sign assertion using registered device private key
5. POST /v1/core/transfers/{transferId}/confirm

Expected result

• confirmation succeeds;
• API returns next step;
• funding webview URL may be returned.

Negative tests

---

18. Funding webview test

Goal

Confirm the partner app can open and resume from funding webview.

Steps

1. Receive fundingWebviewUrl
2. Open webview
3. Complete or simulate funding
4. Return to app
5. GET /v1/core/transfers/{transferId}

Expected result

• webview opens successfully;
• app resumes after close/return;
• transfer status updates;
• customer sees latest state.

Negative tests

---

19. Transfer status polling test

Goal

Confirm the app can display transfer history and detail.

Tests

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

Expected result

• detail endpoint returns the selected transfer;
• list endpoint returns customer transfer history;
• pagination works where applicable;
• terminal states stop polling.

---

20. Cancellation test

Goal

Cancel an eligible transfer.

Steps

1. GET /v1/core/transfers/{transferId}
2. Confirm cancellation is available
3. POST /v1/core/transfers/{transferId}/cancel
4. GET /v1/core/transfers/{transferId}

Expected result

• cancellation request is accepted when eligible;
• transfer detail shows cancellation progress or outcome;
• app handles pending cancellation if returned.

Negative tests

---

21. Error handling test matrix

---

22. Idempotency test

Goal

Confirm duplicate requests do not create duplicate actions.

Test pattern

1. Send action request with Idempotency-Key A
2. Repeat same request with Idempotency-Key A
3. Confirm same result or safe replay response
4. Send different request with Idempotency-Key A
5. Confirm conflict or rejection

Test on:

• quote acceptance;
• transfer submission;
• transfer confirmation;
• transfer cancellation;
• beneficiary creation, if supported.

---

23. Logging test

Confirm partner logs include:

• endpoint;
• HTTP method;
• timestamp;
• HTTP status;
• X-Correlation-Id;
• idempotency key, if used;
• error code;
• app version;
• sanitized journey reference.

Confirm partner logs do not include:

• passwords;
• OTPs;
• access tokens;
• refresh tokens;
• device private keys;
• full payment instrument data;
• identity document images.

---

24. Postman testing

Recommended Postman folders:

01 Auth
02 Device Registration
03 Profile and KYC
04 Beneficiaries
05 Quotes
06 Transfers
07 Funding
08 Cancellation
09 Negative Tests

Recommended Postman environment variables:

baseUrl=https://api.yes.cash
subscriptionKey=<sandbox-subscription-key>
accessToken=<access-token>
refreshToken=<refresh-token>
correlationId=<uuid>
idempotencyKey=<uuid>
subscriptionId=<subscription-id>
beneficiaryId=<beneficiary-id>
quoteId=<quote-id>
transferId=<transfer-id>
kycSessionId=<kyc-session-id>
fundingSessionId=<funding-session-id>

---

25. Sandbox certification checklist

Before requesting certification review, confirm:

• connectivity test passed;
• registration flow passed;
• login flow passed;
• token refresh passed;
• logout passed;
• device registration passed;
• profile submission passed;
• KYC webview flow passed;
• beneficiary creation passed;
• quote signing passed;
• quote disclosure and acceptance passed;
• transfer submission passed;
• device confirmation passed;
• funding webview passed;
• transfer status polling passed;
• cancellation passed;
• expired token handling passed;
• expired quote handling passed;
• idempotency retry passed;
• not-found handling passed;
• logs include correlation IDs;
• sensitive values are not logged.

---

26. Evidence to provide for certification

Provide the following to YesCash technical onboarding:

• Postman collection or equivalent test evidence;
• test run timestamps;
• correlation IDs for successful flows;
• correlation IDs for tested negative flows;
• active sandbox JWKS URL;
• active sandbox signing kid;
• sample signed quote header and payload;
• device registration test evidence;
• transfer confirmation test evidence;
• webview return handling evidence;
• go-live checklist draft.

Do not provide:

• private signing keys;
• device private keys;
• access tokens;
• refresh tokens;
• customer passwords;
• OTP values.

---

27. Exit criteria

Sandbox testing is complete when the partner app can:

• onboard a customer;
• authenticate returning customers;
• maintain sessions safely;
• register devices;
• complete KYC flow;
• create beneficiaries;
• produce valid signed quotes;
• accept quotes;
• submit transfers;
• confirm transfers;
• complete funding flow;
• show transfer status;
• cancel eligible transfers;
• handle common errors safely;
• pass idempotency tests;
• provide correlation IDs for support.