Paymill 0.1 documentation

PAYMILL API/V2 DOCUMENTATION

To get a foreseeable and resource-oriented function call we have implemented our API with REST. All response objects will be delivered as JSON objects.

For an easy switch from test to live mode PAYMILL supports test keys and live keys. The test key works in the exact same way as the live key, but doesn’t do live credit card transactions. You can always use the test key even if you have activated the live key for your staging server.

The examples shown at the API can be used directly to be implemented in your code or if it is curl you can directly call it in the terminal. Your own test key is already used at the examples.

Check our API on:

Authentication

To authenticate at the Paymill API, you need the private key of your test or live account. You have to use http basic access authentication. Your key has to be set as the username. A password isn’t required and you don’t have to insert one. But if you want, feel free to insert an arbitrary string.

Note

  • Please keep your private keys secure and don’t pass them to anybody. These private keys have extreme secure information for handling the transactions of your shop.
  • All your requests must be made via https. Requests which will be made in another way will fail. This is for security reasons of the submitted data.

Response Codes

Some JSON objects like transactions or refunds include a response code, which specifies more detailed information about the outcome of a preceding request.

The codes are numeric and have 5 digits, the first digit follows the rules of http codes so something like 1xxxx is informational (request received etc.), 2xxxx indicates a successful transaction whereas 4xxxx or 5xxxx are error codes.

Errors

We’ve build a RESTful API - that’s the reason why we are concerned about correct status codes which are returned as JSON objects. But in some cases we don’t have the same syntax as the normal http response has. The basic status codes are:

  • 2xx indicates a successful request
  • 4xx informs you about an error
  • 5xx tells you that we did something wrong

Note

Do not just check the HTTP status code 2xx to verify a successful request, also check the expecting message information, for example transactions or refunds include a response code.

Listviews

We have many listviews for different entities in the API functions. The functionality of these listviews is mainly the same; they only differ in the selectable attributes.

Sort Entries

The JSON response objects can be sorted the way you have requested. In this case you receive the result sorted in the required way to get the result sorted in ascending ([attributename]_asc) or descending ([attributename]_desc) order.

Note

Example: amount: ?order=amount | ?order=amount_asc | ?order=amount_desc

Filter Entries

The JSON response objects can be filtered by their attributes. In this case you can call the API to get the result filtered in the required way. This means that the result objects which don’t fit the filter aren’t delivered.

Note

Example: ?created_at=<timestamp> | ?created_at=<timestamp (from)>-<timestamp (to)>

Payments

The Payment object represents a payment with a credit card or via direct debit. It is used for several function calls (e.g. transactions, subscriptions, clients, ...). To be PCI compliant these information is encoded by our Paymill PSP. You only get in touch with safe data (token) and needn’t care about the security problematic of informations like credit card data.

Payment Object for credit card payments

Attributes

id
string Unique identifier for this credit card payment
type
enum(creditcard,debit)
client
string or null The identifier of a client (client-object)
card_type
string Card type eg. visa, mastercard
country
string Country
expire_month
string Expiry month of the credit card
expire_year
string Expiry year of the credit card
card_holder
string or null Name of the card holder
last4
string The last four digits of the credit card
created_at
integer Unix-Timestamp for the creation date
updated_at
integer Unix-Timestamp for the last update
app_id
string or null App (ID) that created this payment or null if created by yourself.

Payment Object for direct debit payments

Attributes

id
string Unique identifier for this direct debit payment
type
enum(creditcard,debit)
code
string The used Bank Code
account
string The used account number, for security reasons the number is masked
holder
string Name of the account holder
created_at
integer Unix-Timestamp for the creation date
updated_at
integer Unix-Timestamp for the last update
app_id
string or null App (ID) that created this payment or null if created by yourself.

Create new Credit Card Payment with ...

Attributes

token
string Unique credit card token
client
string or null Unique client identifier

Creates a credit card payment from a given token, if you’re providing the client-property, the payment will be created and subsequently be added to the client.

Note

  • You always need a token to create a new credit card payment.

Create new Debit Payment with ...

Attributes

token
string Unique direct debit token
client
string or null Unique client identifier

Creates a direct debit payment from a given token, if you’re providing the client-property, the payment will be created and subsequently be added to the client.

Payment Details

Returns data of a specific payment.

Attributes

id
string Unique identifier for the payment

List Payments

This function returns a JSON object with a list of payments. In which order this list is returned depends on the optional parameter order:

  • count
  • offset
  • created_at

Available filters:

  • card_type=<card_type>
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>
  • type=creditcard | debit

Available status for card_type:

  • visa
  • mastercard
  • maestro
  • amex
  • jcb
  • diners
  • discover
  • china_union_pay
  • unknown (= other not supported brand)

Remove Payment

Deletes the specified payment.

Attributes

id
string Unique identifier for the payment

Preauthorizations

If you’d like to reserve some money from the client’s credit card but you’d also like to execute the transaction itself a bit later, then use preauthorizations. This is NOT possible with direct debit.

A preauthorization is valid for 7 days.

Preauthorization Object

Attributes

id
string Unique identifier of this preauthorization
description
string or null Description for this preauthorization
amount
string Formatted amount which will be reserved for further transactions
status
enum(open, pending, closed, failed, deleted, preauth) Indicates the current status of this preauthorization
livemode
boolean Whether this preauthorization was issued while being in live mode or not
payment
payment object for credit card
client
client object or null
created_at
integer Unix-Timestamp for the creation date
updated_at
integer Unix-Timestamp for the last update
app_id
string or null App (ID) that created this preauthorization or null if created by yourself.

Create new Preauthorization with ...

Use either a token or an existing payment to authorize the given amount.

Notice: The response is a transaction object with the preauthorization as sub object.

Attributes

amount
integer (>0) Amount (in cents) which will be charged
currency
string ISO 4217 formatted currency code
token
either token or payment string The identifier of a token
payment
either token or payment string The identifier of a payment (only creditcard-object)
description
string or null Description for this preauthorization

Preauthorization Details

Returns data of a specific preauthorization.

Attributes

id
string Unique identifier of this preauthorization

Remove Preauthorizations

This function deletes a preauthorization.

Attributes

id
string Unique identifier for the preauthorization

List Preauthorizations

This function returns a JSON object with a list of preauthorizations. In which order this list is returned depends on the optional parameter order:

  • count
  • offset
  • created_at

Available filters:

  • client=<client id>
  • payment=<payment id>
  • amount=[>|<]<integer> e.g. “300” or with prefix: “>300” or “<300”
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>

Transactions

A transaction is the charging of a credit card or a direct debit. In this case you need a new transaction object with either a valid token, payment, client + payment or preauthorization. Every transaction has a unique identifier which will be generated by Paymill to identify every transaction. You can issue/create, list and display transactions in detail. Refunds can be done in an extra entity.

Transaction Object

Attributes

id
string Unique identifier of this transaction.
amount
string Formatted amount of this transaction.
origin_amount
integer (>0) The used amount, smallest possible unit per currency (for euro, we’re calculating the amount in cents).
currency
string ISO 4217 formatted currency code.
status
enum(open, pending, closed, failed, partial_refunded, refunded, preauthorize, chargeback) Indicates the current status of this transaction, e.g closed means the transaction is sucessfully transfered, refunded means that the amount is fully or in parts refunded.
description
string or null Need a additional description for this transaction? Maybe your shopping cart ID or something like that?
livemode
boolean Whether this transaction was issued while being in live mode or not.
is_fraud
boolean The transaction is marked as fraud or not.
refunds
list refund objects or null
payment
creditcard-object or directdebit-object
client
clients-object or null
preauthorization
preauthorizations-object or null
created_at
integer Unix-Timestamp for the creation date.
updated_at
integer Unix-Timestamp for the last update.
response_code
integer Response code
short_id
string Unique identifier of this transaction provided to the acquirer for the statements.
invoices
list PAYMILL invoice where the transaction fees are charged or null.
fees
list App fees or null.
app_id
string or null App (ID) that created this transaction or null if created by yourself.

Fee object

type
string Fee type
application
string Unique identifier of the app which charges the fee
payment
string Unique identifier of the payment from which the fee will be charged
amount
integer Fee amount in the smallest currency unit e.g. “420” for 4.20 €
currency
string ISO 4217 formatted currency code.
billed_at
integer or null Unix-Timestamp for the billing date.

Create new Transaction with ...

You have to create at least either a token or a payment object before you can execute a transaction. You get back a response object indicating whether a transaction was successful or not.

Note

The transaction will not be charged at the bank if the test keys are implemented in your code. Please use only the test credit cards mentioned in the documentation.

Attributes

amount
integer (>0) Amount (in cents) which will be charged
currency
string ISO 4217 formatted currency code
description
string or null A short description for the transaction
client
string or null The identifier of a client (client-object) When this parameter is used, you have also to specify a payment method which is not assigned to a client yet. If you attempt to use this parameter when creating a transaction and when specifying a token or preauthorization, the specified client will be ignored.
token
string A token generated through our JavaScript-Bridge When this parameter is used, none of the following should be used: payment, preauthorization.
payment
string The identifier of a payment (creditcard-object or directdebit-object) When this parameter is used, none of the following should be used: token, preauthorization.
preauthorization
string The identifier of a preauthorization (preauthorization-object) When this parameter is used, none of the following should be used: token, payment.
fee_amount
integer or null Fee included in the transaction amount (set by a connected app). Mandatory if fee_payment is set
fee_payment
string or null The identifier of the payment from which the fee will be charged (creditcard-object or directdebit-object). Mandatory if fee_amount is set
fee_currency
string or unset The currency of the fee (e.g. EUR, USD). If it´s not set, the currency of the transaction is used. We suggest to always use as it might cause problems, if your account does not support the same currencies as your merchants accounts.

Transaction Details

To receive the details of an existing transaction, call the unique transaction ID. You can find the ID in the response of the previous request. The return is a refund object with the information of the used payment, client and transaction attributes.

Attributes

id
string Unique identifier of this transaction

Update Transaction

This function updates the description of a transaction.

Attributes

id
string Unique identifier of this transaction
description
string or null Description for the transaction

List Transactions

This function returns a JSON object with a list of transactions. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • count
  • offset
  • created_at

Available filters:

  • client=<client id>
  • payment=<payment id>
  • amount=[>|<]<integer> e.g. “300” or with prefix: “>300” or “<300”
  • description=<string>
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>
  • updated_at=<timestamp> | <timestamp (from)>-<timestamp (to)>
  • status=<string> see list below

Available status for filters:

  • open
  • closed
  • failed
  • preauth
  • pending
  • refunded
  • partially_refunded
  • chargeback

Refunds

Refunds are own objects with own calls for existing transactions. The refunded amount will be credited to the account of the client.

Refund Object

Attributes

id
string Unique identifier of this refund.
transaction
transaction object
amount
integer (>0) The refunded amount.
status
enum(open, pending, refunded) Indicates the current status of this transaction.
description
string or null The description given for this refund.
livemode
boolean Whether this refund happend in test- or in livemode.
created_at
integer Unix-Timestamp for the creation date.
updated_at
integer Unix-Timestamp for the last update.
app_id
string or null App (ID) that created this refund or null if created by yourself.

Refund Transaction

This function refunds a transaction that has been created previously and was refunded in parts or wasn’t refunded at all. The inserted amount will be refunded to the credit card / direct debit of the original transaction. There will be some fees for the merchant for every refund.

Note

  • You can refund parts of a transaction until the transaction amount is fully refunded. But be careful there will be a fee for every refund
  • There is no need to define a currency for refunds, because they will be in the same currency as the original transaction

Attributes

amount
integer (>0) Amount (in cents) which will be charged
description
string or null additional description for this refund

Refund Details

Returns detailed informations of a specific refund.

List Refunds

This function returns a list of existing refunds. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • count
  • offset
  • transaction
  • client
  • amount
  • created_at

Available filters:

  • client=<client id>
  • transaction=<transaction id>
  • amount=[>|<]<integer> e.g. “300” or with prefix: “>300” or “<300”
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>

Clients

The clients object is used to edit, delete, update clients as well as to permit refunds, subscriptions, insert credit card details for a client, edit client details and of course make transactions. Clients can be created individually by you or they will be automatically generated with the transaction if there is no client ID transmitted.

Client Object

Attributes

id
string Unique identifier of this client.
email
string or null Mail address of this client.
description
string or null Additional description for this client, perhaps the identifier from your CRM system?
created_at
integer Unix-Timestamp for the creation date.
updated_at
integer Unix-Timestamp for the last update.
payment
list creditcard-object or directdebit-object
subscription
list or null subscriptions-object
app_id
string or null App (ID) that created this client or null if created by yourself.

Create new Client

This function creates a client object.

Attributes

email
string or null Mail address of the client, is optional if the transaction creates an user itself
description
string or null Description for the client

Client Details

To get the details of an existing client you’ll need to supply the client ID. The client ID is returned by creating a client.

Attributes

id
string Unique identifier for the client

Update Client

This function updates the data of a client. To change only a specific attribute you can set this attribute in the update request. All other attributes that shouldn’t be edited aren’t inserted. You can only edit the description, email and credit card. The subscription can’t be changed by updating the client data. This has to be done in the subscription call.

Attributes

id
string Unique identifier for the client
email
string or null mail address of the client.
description
string or null Description for the client

Remove Client

This function deletes a client, but your transactions aren’t deleted.

Attributes

id
string Unique identifier for the client

List Clients

This function returns a JSON object with a list of clients. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • count
  • offset
  • creditcard
  • email
  • created_at

Available filters:

  • payment=<payment id>
  • subscription=<subscription id>
  • offer=<offer id>
  • description=<string>
  • email=<email>
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>
  • updated_at=<timestamp> | <timestamp (from)>-<timestamp (to)>

Export Client List

This function returns CSV seperated by semicolons, encapsulated by double quotes, with a list of clients. The following parameters can be used:

  • count
  • offset
  • creditcard
  • email
  • created_at

Offers

An offer is a recurring plan which a user can subscribe to. You can create different offers with different plan attributes e.g. a monthly or a yearly based paid offer/plan.

Offer Object

Attributes

id
string Unique identifier of this offer
name
string Your name for this offer
amount
integer (>0) Every interval the specified amount will be charged. Only integer values are allowed (e.g. 42.00 = 4200)
interval
string Defining how often the client should be charged. Format: number DAY | WEEK | MONTH | YEAR Example: 2 DAY
trial_period_days
integer or null Give it a try or charge directly?
created_at
integer Unix-Timestamp for the creation Date
updated_at
integer Unix-Timestamp for the last update
subscription_count
subscription_count Attributes: (integer) if zero, else (string) active, (integer) if zero, else (string) inactive
app_id
string or null App (ID) that created this offer or null if created by yourself.

Create new Offer

With this call you can create an offer via the API. You can also create an offer with the merchant cockpit.

Attributes

amount
integer (>0) Amount (in cents)
currency
string ISO 4217 formatted currency code
interval
string Defining how often the client should be charged. Format: number DAY|WEEK|MONTH|YEAR Example: 2 DAY
name
string Your name for this offer
trial_period_days
integer or null Give it a try or charge directly?

Offer Details

Getting detailed information about an offer requested with the offer ID.

Attributes

id
string Unique identifier for the offer

Update Offer

Updates the offer. If the offer is assigned to a client only the name can be changed all other attributes cannot be edited.

Attributes

id
string Unique identifier for the offer
name
string Your name for this offer

Remove Offer

You only can delete an offer if no client is subscribed to this offer.

Attributes

id
string Unique identifier for the offer

List Offers

This function returns a JSON object with a list of offers. In which order this list are returned depends on the optional parameter order. The following parameters can be used:

  • count
  • offset
  • interval
  • amount
  • created_at
  • trial_period_days

Available filters:

  • name=<name>
  • trial_period_days=<integer>
  • amount=[>|<]<integer> e.g. “300” or with prefix: “>300” or “<300”
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>
  • updated_at=<timestamp> | <timestamp (from)>-<timestamp (to)>

Subscriptions

Subscriptions allow you to charge recurring payments on a client’s credit card / to a client’s direct debit. A subscription connects a client to the offers-object. A client can have several subscriptions to different offers, but only one subscription to the same offer.

Subscription Object

Attributes

id
string Unique identifier of this subscription.
offer
offer object
livemode
boolean Whether this subscription was issued while being in live mode or not.
cancel_at_period_end
boolean Cancel this subscription immediately or at the end of the current period?
trial_start
integer or null Unix-Timestamp for the trial period start
trial_end
integer or null Unix-Timestamp for the trial period end.
next_capture_at
integer Unix-Timestamp for the next charge.
created_at
integer Unix-Timestamp for the creation Date.
updated_at
integer Unix-Timestamp for the last update.
canceled_at
integer or null Unix-Timestamp for the cancel date.
payment
payment object for credit card or payment object for direct debit
client
client object
app_id
string or null App (ID) that created this subscription or null if created by yourself.

This function connects the offer with a client.

Create new Subscription

This function creates a subscription between a client and an offer. A client can have several subscriptions to different offers, but only one subscription to the same offer. The clients is charged for each billing interval entered.

Attributes

offer
string Unique offer identifier
payment
string Unique payment identifier
client
string Unique client identifier. If not provided the client from the payment is being used.
start_at
integer or null Unix-Timestamp for the trial period start

Subscription Details

This function returns the detailed information of the concrete requested subscription.

Attributes

id
string Unique identifier for the subscription

Update Subscription

This function updates the subscription of a client. You can change e.g. the cancel_at_period_end attribute to terminate a subscription either immediately or after the next payment. Or you can assign the subscription to another offer (offer=<new_offer_id>).

Attributes

id
string Unique identifier for the subscription
cancel_at_period_end
boolean To terminate a subscription either immediately or after the next payment.
offer
string Unique identifier describing the offer which is subscribed to the client (optional)
payment
string Unique identifier describing a payment of the client

Remove Subscription

This function removes an existing subscription. The subscription will be directly terminated but pending transactions will still be charged.

Attributes

id
string Unique identifier for the subscription

List Subscriptions

This function returns a JSON object with a list of subscriptions. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • count
  • offset
  • offer
  • canceled_at
  • created_at

Available filters:

  • offer=<offer id>
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>

Webhooks

With webhooks we give you the possibility to react automatically to certain events which happen within our system. A webhook is basically a URL where we send an HTTP POST request to, every time one of the events attached to that webhook is triggered. Alternatively you can define an email address where we send the event’s information to You can manage your webhooks via the API as explained below or you can use the web interface inside our cockpit.

Our call to the webhook / email includes a JSON encoded event object with detailed information about the event in it’s POST body.

Events

There are a number of events you can react to. Each webhook can be configured to catch any kind of event individually, so you can create different webhooks for different events. Each Webhook needs to be attached to at least one event.

For example the event subscription.succeeded is triggered every time a successful transaction has been made in our system that is based on a subscription. Shortly after that has been triggered, we will call every webhook you defined for this event and send detailed information to it.

Webhook Object

Attributes

id
string Unique identifier of this webhook
url
string the url of the webhook
email
string either the email OR the url have to be set and will be returned
livemode
you can create webhooks for livemode and testmode
event_types
array of event_types
active
boolean if false, no events will be dispatched to this webhook anymore
app_id
string or null App (ID) that created this webhook or null if created by yourself.

Create new URL Webhook

With this call you can create a webhook to a url via the API.

Attributes

url
string the url of the webhook
event_types
array includes a set of webhook event types as strings
active
true|false can be used to create an inactive webhook in the beginning

Create new E-Mail Webhook

Instead of setting the url parameter you can set the email parameter to create a webhook, where we send mails to in case of an event.

Attributes

email
string the webhooks email. must be a valid mail address
event_types
array includes a set of webhook event types as strings
active
true|false can be used to create an inactive webhook in the beginning

Webhook Details

Getting detailed information about a webhook requested with the webhook id.

Update Webhook

Updates the webhook. You can change the url/email, the event types and the active state.

Attributes

url
string the url of the webhook
email
string the email for the webhook
event_types
array of event_types
active
true|false activate / deactivate webhook

Remove Webhook

All pending calls to a webhook are deleted as well, as soon as you delete the webhook itself.

List Webhooks

This function returns a JSON object with a list of webhooks. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • count
  • offset
  • url
  • email
  • created_at

Available filters:

  • email=<email>
  • url=<url>
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>

Internal Objects

Here you find the internal objects which do not have a public API endpoint yet.

Fee Object

To find out how collecting application fees click here.

Attributes

type
string Recipient of the fee
application
string If App fee, app object ID (optional)
payment
string Payment object ID from which the fee gets paid
amount
integer Formatted fee amount
currency
string ISO 4217 formatted currency code
billed_at
integer Unix-Timestamp for the creation date

Invoice Object

Attributes

invoice_nr
string invoice number
netto
integer Formatted netto amount
brutto
integer Formatted brutto amount
status
string Invoice status (e.g. sent, trx_ok, trx_failed, invalid_payment, success, 1st_reminder, 2nd_reminder, 3rd_reminder, suspend, canceled, transferred)
period_from
integer Unix-Timestamp for the start of this invoice period
period_until
integer Unix-Timestamp for the end of this invoice period
currency
string ISO 4217 formatted currency code.
vat_rate
integer VAT rate of the brutto amount
billing_date
integer Unix-Timestamp for the billing date
invoice_type
enum(paymill, wirecard, acceptance etc.) Indicates if it”s a PAYMILL invoice or an acquirer payout.
last_reminder_date
integer Unix-Timestamp for last payment reminder

Merchant Object

Attributes

identifier_key
string Unique identifier of this merchant.
email
string email address
locale
string culture setting
country
string country code
currencies
List of activated currencies (ISO 4217 formatted) Deprecated. This information is now part of payment_methods
methods
List of activated card brands

Payment method Object

Attributes

type
string Card brand (e.g. visa, mastercard, amex, elv, sepa etc.)
currency
string ISO 4217 formatted currency code.
acquirer
string Acquiring bank enum(wirecard, acceptance, none)
Contact Support