Skip to content

Integrator payments

An integrator submits payments for merchants using its own client certificate. The merchant remains the actual seller and receives the customer’s bank transfer. Net Money charges the integrator for its submissions.

Confirm with your assigned Net Money Integration Manager that integrator payments are available for your account and environment. Unavailable integrator submissions return HTTP 403, code 18028. Integrator requests cannot use optional Stripe Checkout handover.

Who submits, receives funds, and pays fees

Section titled “Who submits, receives funds, and pays fees”
Role Direct merchant A Integrator I submitting for A
Caller authenticated by mTLS A I
Actual seller and beneficiary A A
Account billed for Net Money fees A I

Your client certificate identifies the account submitting the request. Net Money determines the account to bill from that authenticated account. Send only the request fields listed in the API reference.

sellerEntityId identifies the actual merchant. An integrator must supply it. A direct merchant may omit it; a supplied value must match its own certificate account. A merchant assigned to an integrator can still submit directly with its own credentials. Its direct payments remain billed to that merchant.

Customer funds go to the seller’s approved receiving account. Net Money fees are invoiced separately, rather than deducted from the customer’s transfer. An integrator’s invoice groups its own submissions with seller-specific fee lines; another merchant’s direct traffic is outside that group. A merchant’s direct payments remain separate from payments you submit for that merchant.

Ask Net Money to confirm these settings:

  1. Your certificate belongs to the integrator account and is active and current. Follow the certificate guide for key and CSR creation; use the integrator account when requesting issuance.
  2. Your integrator account is authorized to submit payments for the selected merchant. Working with a related company does not automatically grant access to its merchant accounts.
  3. The selected merchantOpportunityId belongs to that merchant. The merchant’s receiving account and both HTTPS return URLs have been agreed with Net Money.
  4. Your integrator account has a complete billing address: street, city, postcode, and country.

The same opportunity reference can exist for different sellers. Always pair it with the intended sellerEntityId.

Save the following as payment.json. Replace seller-a and online-shop with identifiers supplied for your seller and opportunity:

{
"sellerEntityId": "seller-a",
"idempotencyKey": "integrator-order-20051",
"merchantTransaction": {
"monetaryValue": { "amount": 39.99, "currencyCode": "EUR" },
"merchantOpportunityId": "online-shop",
"merchantTransactionId": "order-20051",
"merchantReference": "Order 20051",
"country": "DE"
}
}

Send it with the integrator’s certificate and key:

Terminal window
export GATEWAY_URL=https://gateway.example.com
curl --cert integrator.crt --key integrator.key \
--header 'Content-Type: application/json' \
--data-binary @payment.json \
"$GATEWAY_URL/v1/payment"

Use the environment URL and account identifiers supplied by your Integration Manager. The example values are placeholders. For a private server CA, add --cacert net-money-ca.crt. Keep server certificate verification enabled.

A successful HTTP 200 response contains a public transaction ID and the payer’s checkout URL. An illustrative response is:

{
"transactionId": "267K3M9W2R5X8N4T6P",
"redirectUrl": "https://checkout.example.com/session/example"
}

Direct the payer to the returned redirectUrl. Use the request structure above, with the merchant’s own sellerEntityId and merchantOpportunityId. The receiving account and success/failure return URLs are configured with your Integration Manager. Integrator requests do not accept return URL or receiving-account overrides, or the optional checkout field.

Net Money scopes an idempotencyKey to the authenticated caller and the actual seller. Keep the same caller, seller, key, and merchantTransaction when retrying after a timeout or lost response.

  • An identical authorized retry returns the original payment’s transactionId.
  • Changed business data under the same caller/seller/key returns HTTP 409, code 13002. Keep the original request for retries; use a new key only for an intentionally new payment.
  • A key used for another seller or by another caller identifies a separate submission. Reusing merchantTransactionId with a different key does not deduplicate the payment.
  • Rotating a certificate within the same account preserves the caller identity and key scope. Use the account’s active current certificate, rather than an old certificate retained with a payment.

An accepted payment keeps the receiving account and success/failure return URLs agreed when it was created. Retrying the same payment preserves those destinations; changes to your configuration apply to new payments. The returned checkout session URL is separate from those return URLs.

Retries still require a valid certificate and permission to act for the same merchant. If access has changed or the outcome is uncertain, contact your Integration Manager and retain the original request and key. A new key can create a second payment.

Revoking access does not guarantee cancellation of payments already in progress. Contact your Integration Manager if you need help with an existing payment.

Confirm your status, callback, and reporting requirements with your Integration Manager before integration:

  • Status requests must use a certificate for the merchant that owns the payment. An integrator’s own certificate does not provide access to that merchant’s payment status; requests outside the authenticated account return 404.
  • Callback URL and secret settings apply to the authenticated account. Confirm the supported callback setup for your integration with your Integration Manager.
  • Consolidated reports across your merchants are unavailable. See Reporting scope for the reports available to each merchant account.

Use the Gateway error reference to handle validation errors, access restrictions, configuration problems, and unsuccessful requests.