The SDK needs five values. Collect them before you initialize:
| Value | Example | Where to find it |
|---|---|---|
| API username | USxxxxxxxxxxxxx | Finix Dashboard. Your API credential pair for the target environment. |
| API password | {your_api_secret} | Issued with the username. Treat it as a secret. |
| Merchant ID | MUxxxxxxxxxxxxx | The Finix Merchant the payments settle to. |
| Merchant MID | 123456789012345 | The merchant's processing MID, shown on the merchant's profile. |
| Device ID | DVxxxxxxxxxxxxx | Created in Set up a Device. |
You also pass the merchant's display name; Apple shows it to the Buyer on the tap screen.
An environment is a pairing of Finix and Apple environments, and the two must match on the test device:
- Finix: Sandbox and Production are completely separate, and each has its own credentials and merchants. In the SDK, the environment is explicit:
.sandboxis for integration and testing (all examples in this guide run against Sandbox);.productionis for live payments. A configuration's credentials, merchant, and Device must all belong to the same environment; mixing environments is a common cause of authentication and token errors. - Apple: the Apple Account signed in on the iPhone determines which Apple environment handles the Terms and Conditions flow and card reads. Sandbox testing requires a Sandbox Apple Account (created in App Store Connect) signed in as the device's primary Apple Account; see Set up the iPhone for sandbox testing for the setup steps. In Production, the merchant's iPhone is signed in with their regular Apple Account.
A complete Sandbox test setup uses a .sandbox configuration with Sandbox credentials, merchant, and Device, on an iPhone signed in with a Sandbox Apple Account. For Production validation, use a .production configuration with Production credentials, merchant, and Device, on an iPhone signed in with a regular Apple Account.
When you switch to .production, swap in Production API credentials, a Production merchant, and a Device created against the Production API (https://finix.live-payments-api.com), and validate on an iPhone signed in with a regular Apple Account instead of a Sandbox tester. The rest of your integration stays the same.
API credentials embedded in an app binary can be extracted. Instead of compiling them in, have your backend deliver the credential pair, merchant details, and Device ID to the app at session start, scoped to the signed-in merchant. The SDK holds them in memory and only uses them over TLS connections to Finix.
Next: Set up a Device.