Onboarding
Before you start the integration, you exchange credentials with Mercuryo and configure two Apple Pay certificates.
What Mercuryo Provides
Dashboard access
You need access to the Mercuryo Dashboard — contact your integration manager if you don't have credentials yet.
Mercuryo API credentials
| Parameter | Description |
|---|---|
widget_id |
Your Widget ID, available in the Mercuryo Dashboard under Widgets → select your widget. Used in the Mercuryo widget URL for the KYC handover. |
Sdk-Partner-Token |
Your partner authentication token for the quote, the payment request and the KYC requests. Request it from your integration manager. |
| Sign Key | The key used to sign payment requests (X-Signature) and to verify callbacks — see Signature. Available in the Mercuryo Dashboard under Widgets → select your widget. Keep it confidential. |
Certificate Setup
This integration relies on a two-certificate model to ensure maximum security and a clear separation of responsibilities. Configure both certificates before you begin the integration.
1. Merchant Identity Certificate
- Purpose: to authenticate your server with Apple's servers when validating a merchant session. This certificate is used to establish a secure TLS connection for the session validation request.
- Responsibility: yours.
- Action: generate this certificate in your Apple Developer account and securely store it along with its private key on your backend infrastructure. You use it to handle the
onmerchantvalidationstep — see Validate the merchant session. Mercuryo never sees this certificate or its key. - Official documentation: Creating a Merchant Identity Certificate.
2. Payment Processing Certificate
- Purpose: to allow Mercuryo to decrypt the payment token. Apple uses the public key of this certificate to encrypt the payment data.
- Responsibility: ours to initiate, yours to generate, ours to use.
- Action: during onboarding, Mercuryo provides you with a Certificate Signing Request (CSR). Upload this CSR to your Apple Developer account to generate the Payment Processing Certificate (
.cerfile), then securely provide the downloaded.cerfile back to Mercuryo. Mercuryo uses this certificate, paired with its private key, to process payments on your behalf. - Official documentation: this certificate is associated with your Merchant ID and is used for encrypting payment data. See Apple's guide on configuring Apple Pay.
Callback URL
Set a secure (HTTPS) URL where Mercuryo sends transaction status updates in the Callback URL field of your widget settings in the Mercuryo Dashboard, or provide it to your integration manager during onboarding. See Callbacks & Webhooks.
Environments
| Service | Production | Sandbox |
|---|---|---|
| Dashboard | https://dashboard.mercuryo.io |
https://sandbox-dashboard.mrcr.io |
| API | https://api.mercuryo.io/v1.6 |
https://sandbox-api.mrcr.io/v1.6 |
| Widget (KYC handover) | https://exchange.mercuryo.io |
https://sandbox-exchange.mrcr.io |