Setup steps
Select the base URL
Use the base URL that matches the environment of your ApiKey.
| Environment | Base URL |
|---|---|
| Production | https://issuer.onerway.com/api/v1/merchant |
| Sandbox | https://sandbox-issuer.onerway.com/api/v1/merchant |
ApiKey must come from the same environment.Create a sandbox merchant account
Provide your email address, source IP address, and event callback URL to Onerway. After the sandbox account is created, sign in to the merchant portal from the email link and obtain the merchant number and secret key used for integration and webhook verification.
Provide source IP addresses
Send your stable server source IP addresses to Onerway so they can be added to the Issuing allowlist.
- Provide only stable server source IP addresses.
- If sandbox and production use different source IP addresses, provide them separately.
- If a source IP address changes, update the allowlist before switching traffic.
Store credentials securely
Issuing APIs identify caller permissions through the ApiKey request header. Store the ApiKey, merchant number, and webhook secret on your server.
Configure event callbacks
Configure a server-side callback URL that can receive card operation and transaction event webhooks. The callback must verify x-signature, deduplicate events by request_id, and return respCode=20000 after accepting an event.
Integration flow
| Step | Action | Endpoint or source |
|---|---|---|
| 1 | Get card product information and confirm the productId with Onerway. | Card product list |
| 2 | Create a cardholder that matches the card product. | Create cardholder |
| 3 | Create a card with productId, cardholderId, and the deposit amount. | Create card |
| 4 | Query card operation progress, basic card information, balance, and sensitive information when needed. | Card queries |
| 5 | Receive card operation event notifications. | Card operation event |
| 6 | Query card transaction records and receive transaction event notifications. | Query transaction records |
Next steps
- API specifications — review common Issuing API rules
- Create cardholder — create a cardholder before card creation
- Create card — create the first virtual card
- Event webhooks — configure card operation and transaction event handling