PAYMILL Unite How-To

PAYMILL Unite is a new set of features dedicated to market-place-like businesses.
With Unite you can

• Get permission from PAYMILL merchants to execute API calls over their account
• Create transactions through your connected merchants and collect transaction fees

In order to connect with you, merchants have to go through an authorization workflow. This workflow is built on OAuth2. The general approach is as follows:

• request authorization to access a merchant's account,
• create an API key for the merchant's account when authorized,
• access our API by using the newly created API key.

Registering an application

Navigate to our Cockpit and open the My Account: Settings page. In the “App” tab you can register a new application. You can create up to 10 applications in your account. As application's don't depend on the live/test mode of your cockpit, you will see them all in both modes.

OAuth2 Workflow

The OAuth2 workflow consists of three steps. First you request an authorization from the merchant by redirecting him to PAYMILL. If he grants you the requested permissions, we redirect him back to you together with an authorization code. With this code you can request an access token (which is the same as the api key in our case). After you got the access token, you can execute API calls with it on the merchants account. The access token might be invalidated over time (for security reasons). If this happens you can request a new one without requesting authorization again by using refresh tokens you get together with the access token.
If a access_token is not valid any more you get the following error on API-calls: key_inactive

The following paragraphs describe the technical details for these steps.

Requesting an authorization code

To request an authorization code for another merchants account, you’ll have to redirect that merchant to the authorization page on our servers.

The target url for this redirect https://connect.www.paymill.org/authorize and you need to append a few query parameters to the GET request:

• client_id (required): The App ID which you find on the App tab in your settings.
• response_type (required): fixed string set to "code".
• scope (required): a space-separated list of permissions you want to request. You get more information about permissions further down.
• redirect_uri (optional): if you set this, it is used to redirect the merchant to this uri, instead of the static redirect_uri from your App settings. This enables you to use dynamic uris, e.g. for different servers. If you use this feature it is highly recommended to use the checksum parameter too, as otherwise the service will be vulnerable to diverse attacks.
• custom_param (optional): whatever you send in this parameter will just be appended to the redirect uri, when we send the merchant back to you. This can be used together with the static redirect uri to identify the merchant, once he comes back. This string has to be url encoded.
• checksum (optional): to verify the correctness of the query string you can add the checksum parameter (see checksum validation).

When the merchant is redirected back to your page, we'll append a few query parameters to the uri you provided when registering your application, depending on the outcome of the request.

If the merchant authorizes your request, the parameter code, containing your authorization code, is appended.

If an error occurs or if the merchant denies authorization, the parameters error and error_description are appended. error contains an error key, error_description a descriptive message for that error in english. If you want to react to errors programmatically, always rely on the error key and not on the error_description.

Success response:

Error response:

Checksum validation

To verify the correctness of the query string you can add a checksum parameter

The checksum is generated with HMAC. The used algorithm is sha256 and the hash key is your hash token. It has to be created over the complete query string and has to be added (at the end) to the query string as the parameter checksum afterwards.

Example

Connect URL:

<QUERY_STRING>:

Hashing function (example in PHP):

Resulting checksum:

New connect URL with checksum:

If you want to use the optional parameters redirect_uri and/or custom_param you also need to include them into the query string to have a valid connect URL.

Permissions

There are 3 different privileges for each PAYMILL API endpoint:

• Read: read all objects from this api endpoint.
• Write: write objects to this api endoint, read and edit objects writen by yourself.
• ReadWrite: read all objects, write new objects, edit anything.

A permission is specified by the name of an api endpoint, like transactions, followed by an underscore, followed by r (read), w (write), or rw (read and write).

Example: transactions_rw (read and write transactions), clients_r (read clients), refunds_w (create new refunds).

Currently possible endpoints: clients, offers, payments, preauthorizations, refunds, subscriptions, transactions, webhooks.

Creating the access token

If a merchant authorized your request you are handed an authorization code you can exchange for an access token. The access token as described in OAuth2 is a private api key to your merchants account. The api key is also equipped with the permissions you specified during the authorization request.

In order to create the access token, you have to call the access token endpoint at https://connect.www.paymill.org/token with a POST request. The request body must contain the request parameters using application/x-www-form-urlencoded format.

• client_id (required): the application id you created when registering an application.
• client_secret (required): the access key as show in your app settings. This is automatically the same value as your private api key / private test api key)
• grant_type (required): string set to the fixed value "authorization_code"
• code (required): the authorization code retrieved earlier

A successful response contains a private api key to the merchants account plus his public api key and a refresh token. If the private api key is a live key, then the response also includes the currencies and payment methods supported by the merchant. The response is sent as application/json:

• access_token is the private access key for the merchant account. If live access keys are available it's the same as live access key else same test access key.
• expires_in expiration timestamp. In our case this is always null. This tells that the access_key does not expire.
• token_type defines the token type (not important).
• scope the permissions connected with this access_token
• refresh_token is the code you need to do refresh token request.
• merchant_id is the unique identifier of the connected merchant.
• is_active is true if the merchant can do live transaction with the mentioned payment_methods.
• payment_methods may contain a list of active payment methods which are combinations of card type, currency and acquirer:
• type may contain one of the following values:
• visa: Visa cards
• mastercard: MasterCard cards
• amex: American Express cards
• jcb: JCB cards
• dinersclub: DinersClub cards
• cup: China UnionPay cards
• elv: Direct debit (ELV, Germany only).
• currency may contain every 3-letter currency code supported by PAYMILL and specified by ISO 4217
• acquirer may contain one of our recent acquirer ("acceptance", "wirecard") for your payment method configuration.
• access_keys contains test and live keys. Live keys are available only if the connected merchant can do live transactions.
• public_key is the public key of the merchant. If live access keys are available it's the same as live access key else same test access key.

If something went wrong, an error response is returned as follows:

Possible errors are ...

Refreshing an access token

Whenever requesting an access token (either by providing an authorization code or refresh token) you are given a refresh token along side with the access token. This refresh token can be used to generate a new access token at any time.

Trading a refresh token for an access token works similarly as creating an access token with an authorization code: you POST a few parameters to https://connect.www.paymill.org/token and receive an access token response as described in Creating the access token.

Possible parameters contain ...

• client_id (required): the application id you created when registering your application
• client_secret (required): the access key as show in your app settings. This is automatically the same value as your private api key / private test api key)
• grant_type (required): fixed string set to refresh_token
• refresh_token (required): the refresh token as given when the last access token was created.
• scope (optional): optional set of privileges for the new access token. Must be a subset of the originally requested privileges. Set to the originally requested privileges if omitted.

The response is identical to the one described in Creating the access token.

API extensions for applications

Collecting application fees

If creating a transaction through a merchant's PAYMILL account, you can collect a fee for this transaction by adding the fee_amount, fee_payment and optionally the fee_currency parameter. The fee is specified in the same format as the transaction amount. The fee payment should represent a payment of the merchant which will be billed in order to collect the fee:

This request will charge an amount of 42.00€ through the merchants account. PAYMILL will collect the default disagio and transaction fee. Your additional fee is drawn from the remaining amount.

The transaction now also contains a list of fee objects:

Sharing payment information

When accessing our API by using an API key from your merchant, all objects which are created are also only available in this merchant account. This is not desirable for payment information as you probably wan't to store it on your own account and use it for transactions on your merchant's accounts.

In order to achieve this, you can use a payment objects and token with all merchants which are connected to your application. This is true for all API endpoints which accept a payment id or token as a POST parameter.

The general approach is as follows (for example with transactions):

1. You post a payment id as payment parameter, along with client, amount and currency to https://api.www.paymill.org/v2/transactions
2. We lookup the payment and client in the merchant account the used API key is valid for.
3. If the lookup fails, we look up the payment and client in the application's merchant account.
4. If this lookup fails to, we return the usual API error ("payment not found").
5. If either lookup succeeds, we use the found payment object.
6. If it's a payment object from the application's merchant account, the object is duplicated and stored with the merchant's account.
7. The transaction object is returned, containing the payment information.

The same process is true for the token parameter.

Webhooks for applications

There are some special webhook events available for Unite:

• app.merchant.activated: triggered as soon as a connected merchant completed the activation process. Live keys only become valid after this event.
• app.merchant.deactivated: triggered if a merchant, which has been activated previously gets deactivated again. This might be triggered together with app.merchant.rejected.
• app.merchant.rejected: triggered if a newly connected merchant is rejected during his activation process. Live keys will never become valid if this event occurs.
• app.merchant.pm.update: triggered if a merchant payment method has become active or inactive. The message will contain all recently active payment methods and an information which one has changed.
• app.merchant.app.disabled: triggered, when a merchant disables an application he previously granted access to his account
• app.merchant.live_requests_allowed: triggered, when merchant allows live requests for an application
• app.merchant.live_requests_not_allowed: triggered, when merchant denies live requests for an application

These webhooks can be registered to the application's account and are triggered for every merchant who connects to this application.

The webhook data contains the user_id (the parameter merchant in the result) which was already given to you upon the access token request. This id can be used to match a webhook call to an authorization / connect attempt.

Example: