Adding merchants and their gateways

Creating merchants, setting their gateway credentials, giving them API keys, and getting them ready to take real payments.

Creating a merchant account

Create a merchant for each business you serve with POST /api/merchant-accounts using your provider key, or in the Portal under Merchants. You choose the external reference, which is how you refer to the merchant in every later request, so use an id from your own system. A reference that already exists returns 409. List your merchants with GET /api/merchant-accounts.

Merchants who sign up through your sign-up link appear in the same list with a Self-signup badge.

Setting up gateway credentials

A merchant needs credentials for at least one payment gateway before it can take a payment. Set them with PUT /api/merchant-accounts/{externalReference}/credentials/{gatewayName}, or in the Portal under Manage credentials on the merchant's page.

• GET .../credentials lists which gateways are configured, without revealing secrets.
• DELETE .../credentials/{gatewayName} removes one.
• A merchant can have more than one gateway. Choose the default gateway on the credentials page, and name a gateway explicitly on an invoice when you want a different one.

Credentials are stored encrypted and are never shown again. Merchants can also set their own gateway credentials from their own settings if you would rather they did.

Issuing a merchant API key

A merchant does not need its own key, because your provider key already works for it. Issue one when a merchant integrates directly or you want its access separate from yours.

• POST /api/merchant-accounts/{externalReference}/api-key issues a key and returns it once. Calling it again rotates the key.
• DELETE /api/merchant-accounts/{externalReference}/api-key revokes it. Your provider key keeps working either way.
• In the Portal the same actions are on the merchant's page under API key.

The key matches the deployment: sandbox issues pmw_test_ keys and production issues pmw_live_ keys. A merchant key reaches only that merchant and cannot create merchants or issue keys.

Merchant checklist before going live

1. Gateway credentials are set for the live environment, and the default gateway is correct.
2. Business details, logo and support reply-to are filled in.
3. A default tax rate is set, and products and tax rates are loaded if the merchant will invoice.
4. A subscription plan is chosen on the merchant's Billing page and a card is on file (unless you cover the merchant under the Enterprise program).
5. A test invoice has been paid and refunded end to end.
6. Webhooks are registered with the gateway for this merchant. See webhooks.

Moving saved cards from another gateway

A merchant who already has saved cards or bank accounts at its current gateway does not have to ask customers to re-enter them. PayMidWare can move them to a new gateway, with the two processors transferring the cards themselves, or keep charging them where they are. PayMidWare never receives a card number in this process. PayMidWare staff run the migration with you and the merchant, and the merchant sees the status on its dashboard. Contact us to scope one.