Test mode
Run the same endpoints in a sandbox with test credentials. No money is charged and no courier is sent.
Test credentials run the same endpoints in a sandbox. Transfers are created, move through their statuses, and fire webhooks, but no money is charged and no courier is sent. Nothing changes for live integrations, and no request or response field is different in test mode.
To get test credentials, see Authentication.
Behaviour by endpoint
| Endpoint | Test mode behaviour |
|---|---|
POST /auth/token | Works with test credentials. Same response. |
| Warehouse endpoints | Shared with live. The same warehouses appear with either credential set. Changing a warehouse in test mode changes the real warehouse. |
POST /options | Real quote with real prices. The quote is tagged as a test quote. |
POST /transfer | Creates a test transfer. The balance is not checked or debited, so it works on an unfunded account. Nothing is sent to recipients or couriers. |
GET /transfer/{transferId} | Returns the test transfer, with statuses advancing on a timer. |
POST /transfer/{transferId}/cancel | Same rules as live (only before shipping starts). Nothing is refunded, since nothing was charged. |
Warehouses are not sandboxed
Test mode does not isolate warehouses. Edit or delete them with care.
Test and live data are separate
- Test credentials only see test quotes and test transfers. Live credentials only see live ones.
- Using an ID from the other mode returns the normal not-found errors:
404 TRANSFER_NOT_FOUNDfor transfers and404 MATCHMAKING_NOT_FOUNDfor quotes. It is never a permission error, so neither mode reveals that the other's IDs exist. - A quote taken with test credentials cannot be turned into a transfer with live credentials, or the reverse.
What does not happen to test transfers
- No balance debit or refund.
- No SMS, push, or email to the recipient.
- No courier assignment.
- No appearance in your dashboard transfer list or statistics.
Simulated delivery lifecycle
Nothing physically ships a test parcel, so Melo moves it along automatically after POST /transfer returns:
| Time after creation | What happens |
|---|---|
| Immediately | The transfer is inProgress, with created and payed completed. |
| About 30 seconds | The shipped step completes. |
| About 60 seconds | The delivered step completes and the transfer becomes completed. |
Each status change sends a webhook. The delays are approximate because the steps run on a background queue.
Simulate failures with recipient phone numbers
Set recipientInfo.phone on POST /transfer to force an outcome. Only digits are compared, so +995 555-000-001 and 995555000001 are the same number.
recipientInfo.phone | Result |
|---|---|
995555000001 | The shipped step fails and the transfer becomes failed. |
995555000002 | Ships normally, then the delivered step fails and the transfer becomes failed. |
995555000003 | Stays at payed and never advances. Useful for testing cancellation or timeouts. |
| Any other number | Ships, then delivers. |
Cancelling a test transfer before it ships stops the simulation. There is no endpoint to advance a test transfer by hand.
Limits and unchanged behaviour
- Rate limits are shared. Test and live traffic count against the same per-client limits. See Errors.
- Quotes expire after the same time window as in live mode.
- Coverage is validated the same way. A pickup or destination outside the service area returns
PICKUP_OUT_OF_SERVICE_AREAorDESTINATION_OUT_OF_SERVICE_AREA, and a destination with no available product returnsNO_PRODUCTS_FOUND, as in live. - There are no idempotency keys, as in live mode. Retrying
POST /transferwith the same quote ID still creates at most one transfer. - Test mode is per merchant and needs test credentials issued from the dashboard.