Paymill 0.1 documentation

If you want to use the PAYMILL API/V2.0, click here: Download v2.0 PDF

PAYMILL API/V2.1 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:

apiary.iomashape

Authentication¶

% curl https://api.www.paymill.org/v2.1/clients \
    -u <DEIN_PRIVATE_KEY>:

$apiKey = '<DEIN_PRIVATE_KEY>';
$request = new Paymill\Request($apiKey);

PaymillContext paymillContext = new PaymillContext(
    "<DEIN_PRIVATE_KEY>"
);
ClientService clientService = paymillContext.getClientService();

var paymill = require('paymill-node')('<DEIN_PRIVATE_KEY>');

import paymill
paymill.api_key = "<DEIN_PRIVATE_KEY>"

# Ruby >= 1.9.x
require 'paymill'
Paymill.api_key = "<DEIN_PRIVATE_KEY>"

PaymillContext paymillContext = new PaymillContext("<DEIN_PRIVATE_KEY>");
ClientService clientService = paymillContext.getClientService();

var pm = require('../paymill.node.js');
pm.initialize("<DEIN_PRIVATE_KEY>");

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¶

`10001`:	General undefined response.
`10002`:	Still waiting on something.

`20000`:	General success response.

`40000`:	General problem with data.
`40001`:	General problem with payment data.
`40100`:	Problem with credit card data.
`40101`:	Problem with cvv.
`40102`:	Card expired or not yet valid.
`40103`:	Limit exceeded.
`40104`:	Card invalid.
`40105`:	Expiry date not valid.
`40106`:	Credit card brand required.
`40200`:	Problem with bank account data.
`40201`:	Bank account data combination mismatch.
`40202`:	User authentication failed.
`40300`:	Problem with 3d secure data.
`40301`:	Currency / amount mismatch
`40400`:	Problem with input data.
`40401`:	Amount too low or zero.
`40402`:	Usage field too long.
`40403`:	Currency not allowed.

`50000`:	General problem with backend.
`50001`:	Country blacklisted.
`50002`:	IP address blacklisted.
`50003`:	Anonymous IP proxy used.
`50100`:	Technical error with credit card.
`50101`:	Error limit exceeded.
`50102`:	Card declined by authorization system.
`50103`:	Manipulation or stolen card.
`50104`:	Card restricted.
`50105`:	Invalid card configuration data.
`50200`:	Technical error with bank account.
`50201`:	Card blacklisted.
`50300`:	Technical error with 3D secure.
`50400`:	Decline because of risk issues.
`50500`:	General timeout.
`50501`:	Timeout on side of the acquirer.
`50502`:	Risk management transaction timeout.
`50600`:	Duplicate transaction.

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: client object or null
card_type: string Card type eg. visa, mastercard
country: string or null Country
expire_month: string Expiry month of the credit card
expire_year: string Expiry year of the credit card
card_holder: string 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 ...¶

Token

Request

curl <PAYMILL_URL>payments \
  -u <DEIN_PRIVATE_KEY>: \
  -d "token=098f6bcd4621d373cade4e832627b4f6"

$payment = new Paymill\Models\Request\Payment();
$payment->setToken('098f6bcd4621d373cade4e832627b4f6');

$response = $request->create($payment);

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.payments.create(
    {
    	token: '098f6bcd4621d373cade4e832627b4f6',
	},
    function(err, payment) {
        if (err) {
            console.log("Couldn't create the payment record");
            return;
        }
        console.log("payment id " + payment.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
payment = p.newcard(
  token='098f6bcd4621d373cade4e832627b4f6'
)

Paymill::Payment.create token: "098f6bcd4621d373cade4e832627b4f6"

PaymentService paymentService = paymillContext.PaymentService;
Payment payment = paymentService.CreateWithTokenAsync("098f6bcd4621d373cade4e832627b4f6").Result;

pm.payments.create("098f6bcd4621d373cade4e832627b4f6").then(function(payment) {
	console.log("payment:" + payment.id);
}, function(error) {
	console.log("couldnt create payment:" + error);
});

Response

{
    "data" : {
        "id"           : "pay_3af44644dd6d25c820a8",
        "type"         : "creditcard",
        "client"       : null,
        "card_type"    : "visa",
        "country"      : null,
        "expire_month" : "10",
        "expire_year"  : "2013",
        "card_holder"  : "",
        "last4"        : "1111",
        "created_at"   : 1349942085,
        "updated_at"   : 1349942085,
        "app_id"       : null
    },
    "mode" : "test"
}

Token & Client

Request

curl <PAYMILL_URL>payments \
  -u <DEIN_PRIVATE_KEY>: \
  -d "token=098f6bcd4621d373cade4e832627b4f6" \
  -d "client=client_88a388d9dd48f86c3136"

$payment = new Paymill\Models\Request\Payment();
$payment->setToken('098f6bcd4621d373cade4e832627b4f6')
        ->setClient('client_88a388d9dd48f86c3136');

$response = $request->create($payment);

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.createWithTokenAndClient(
    "098f6bcd4621d373cade4e832627b4f6",
    "client_88a388d9dd48f86c3136"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.payments.create(
    {
    	token: '098f6bcd4621d373cade4e832627b4f6',
        client: 'client_88a388d9dd48f86c3136'
	},
    function(err, payment) {
        if (err) {
            console.log("Couldn't create the payment record");
            return;
        }
        console.log("payment id " + payment.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
payment = p.newcard(
  token='098f6bcd4621d373cade4e832627b4f6',
  client='client_88a388d9dd48f86c3136'
)

Paymill::Payment.create token: "098f6bcd4621d373cade4e832627b4f6",
    client: "client_2a0cf95235a42c758244"

PaymentService paymentService = paymillContext.PaymentService;
Payment payment = paymentService.CreateWithTokenAndClientAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    "client_88a388d9dd48f86c3136"
).Result;

pm.payments.create("098f6bcd4621d373cade4e832627b4f6", "client_88a388d9dd48f86c3136").then(function(payment) {
	console.log("payment:" + payment.id);
}, function(error) {
	console.log("couldnt create payment:" + error);
});

Response

{
    "data" : {
        "id"           : "pay_3af44644dd6d25c820a9",
        "type"         : "creditcard",
        "client"       : "<Object>",
        "card_type"    : "visa",
        "country"      : null,
        "expire_month" : "10",
        "expire_year"  : "2013",
        "card_holder"  : "",
        "last4"        : "1111",
        "created_at"   : 1349942085,
        "updated_at"   : 1349942085,
        "app_id"       : null
    },
    "mode" : "test"
}

Attributes¶

token: string Unique credit card token
client: client object or null

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 ...¶

Token

Request

curl <PAYMILL_URL>payments \
  -u <DEIN_PRIVATE_KEY>: \
  -d "token=12a46bcd462sd3r3care4e8336ssb4f5"

$payment = new Paymill\Models\Request\Payment();
$payment->setToken('12a46bcd462sd3r3care4e8336ssb4f5');

$response = $request->create($payment);

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.payments.create(
    {
    	token: '12a46bcd462sd3r3care4e8336ssb4f5'
	},
    function(err, payment) {
        if (err) {
            console.log("Couldn't create the payment record");
            return;
        }
        console.log("payment id " + payment.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
payment = p.newcard(
  token='12a46bcd462sd3r3care4e8336ssb4f5'
)

Paymill::Payment.create token: "12a46bcd462sd3r3care4e8336ssb4f5"

PaymentService paymentService = paymillContext.PaymentService;
Payment payment = paymentService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6"
).Result;

pm.payments.create("12a46bcd462sd3r3care4e8336ssb4f5").then(function(payment) {
	console.log("payment:" + payment.id);
}, function(error) {
	console.log("couldnt create payment:" + error);
});

Response

{
    "data" : {
        "id"         : "pay_917018675b21ca03c4fb",
        "type"       : "debit",
        "client"     : null,
        "code"       : "12345678",
        "holder"     : "Max Mustermann",
        "account"    : "******2345",
        "created_at" : 1349944973,
        "updated_at" : 1349944973,
        "app_id"     : null
    },
    "mode" : "test"
}

Token & Client

Request

curl <PAYMILL_URL>payments \
  -u <DEIN_PRIVATE_KEY>: \
  -d "token=12a46bcd462sd3r3care4e8336ssb4f5" \
  -d "client=client_88a388d9dd48f86c3136"

$payment = new Paymill\Models\Request\Payment();
$payment->setToken('12a46bcd462sd3r3care4e8336ssb4f5');
$payment->setClient('client_88a388d9dd48f86c3136');

$response = $request->create($payment);

 PaymentService paymentService = paymillContext.getPaymentService();
 Payment payment = paymentService.createWithTokenAndClient(
    "098f6bcd4621d373cade4e832627b4f6",
    "client_88a388d9dd48f86c3136"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.payments.create(
    {
    	token: '12a46bcd462sd3r3care4e8336ssb4f5',
    	client: 'client_88a388d9dd48f86c3136'
	},
    function(err, payment) {
        if (err) {
            console.log("Couldn't create the payment record");
            return;
        }
        console.log("payment id " + payment.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
payment = p.newcard(
  token='12a46bcd462sd3r3care4e8336ssb4f5',
  client='client_88a388d9dd48f86c3136'
)

Paymill::Payment.create token: "12a46bcd462sd3r3care4e8336ssb4f5",
    client: "client_2a0cf95235a42c758244"

PaymentService paymentService = paymillContext.PaymentService;
 Payment payment = paymentService.CreateWithTokenAndClientAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    "client_88a388d9dd48f86c3136"
).Result;

pm.payments.create("12a46bcd462sd3r3care4e8336ssb4f5", "client_88a388d9dd48f86c3136").then(function(payment) {
	console.log("payment:" + payment.id);
}, function(error) {
	console.log("couldnt create payment:" + error);
});

Response

{
    "data" : {
        "id"         : "pay_917018675b21ca03c4fc",
        "type"       : "debit",
        "client"     : "<Object>",
        "code"       : "12345678",
        "holder"     : "Max Mustermann",
        "account"    : "******2345",
        "created_at" : 1349944973,
        "updated_at" : 1349944973,
        "app_id"     : null
    },
    "mode" : "test"
}

Attributes¶

token: string Unique direct debit token
client: client object or null

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¶

curl <PAYMILL_URL>payments/pay_917018675b21ca03c4fb \
  -u <DEIN_PRIVATE_KEY>:

$payment = new Paymill\Models\Request\Payment();
$payment->setId('pay_917018675b21ca03c4fb');

$response = $request->getOne($payment);

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.get("pay_917018675b21ca03c4fb");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.payments.details('pay_917018675b21ca03c4fb',
    function(err, payment) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("payment id " + payment.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
payment = p.getcarddetails(cardid='pay_917018675b21ca03c4fb')

Paymill::Payment.find "pay_8203c63949dfa4d8809aa6d3"

PaymentService paymentService = paymillContext.PaymentService;
Payment payment = paymentService.GetAsync("pay_917018675b21ca03c4fb").Result;

pm.payments.detail("pay_917018675b21ca03c4fb").then(function(payment) {
	console.log("payment:" + payment.id);
}, function(error) {
	console.log("couldnt get payment:" + error);
});

Response

{
    "data" : {
        "id"           : "pay_3af44644dd6d25c820a8",
        "type"         : "creditcard",
        "client"       : null,
        "card_type"    : "visa",
        "country"      : null,
        "expire_month" : "10",
        "expire_year"  : "2013",
        "card_holder"  : "",
        "last4"        : "1111",
        "created_at"   : 1349942085,
        "updated_at"   : 1349942085,
        "app_id"       : null
    },
    "mode" : "test"
}

Returns data of a specific payment.

Attributes¶

id: string Unique identifier for the payment

List `Payments`¶

curl <PAYMILL_URL>payments \
  -u <DEIN_PRIVATE_KEY>:

$payment = new Paymill\Models\Request\Payment();

$response = $request->getAll($payment);

PaymentService paymentService = paymillContext.getPaymentService();
PaymillList<Payment> payments = paymentService.list();

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.payments.list({},
    function(err, payment) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("payment data " + payment.data);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
payments = p.getcards()

Paymill::Payment.all

PaymentService paymentService = paymillContext.PaymentService;
PaymillList<Payment> payments = paymentService.ListAsync().Result;

pm.payments.list().then(function(pmlist) {
	console.log(pmlist.items.length + " payments from total of " + pmlist.count);
}, function(error) {
	console.log("couldnt list payments:" + error);
});

Response

{
    "data" : [
        {
            "id"           : "pay_3af44644dd6d25c820a8",
            "type"         : "creditcard",
            "client"       : null,
            "card_type"    : "visa",
            "country"      : null,
            "expire_month" : "10",
            "expire_year"  : "2013",
            "card_holder"  : "",
            "last4"        : "1111",
            "created_at"   : 1349942085,
            "updated_at"   : 1349942085,
            "app_id"       : null
        }
    ],
    "data_count" : "1",
    "mode" : "test"
}

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`¶

curl <PAYMILL_URL>payments/pay_3af44644dd6d25c820a8 \
  -u <DEIN_PRIVATE_KEY>: \
  -X DELETE

$payment = new Paymill\Models\Request\Payment();
$payment->setId('pay_3af44644dd6d25c820a8');

$response = $request->delete($payment);

PaymentService paymentService = paymillContext.getPaymentService();
paymentService.delete("pay_3af44644dd6d25c820a8");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.payments.remove('pay_88a388d9dd48f86c3136',
    function(err, payment) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("deleted the payment");
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
response = p.delcard(cardid='pay_3af44644dd6d25c820a8')

Paymill::Payment.delete "pay_8203c63949dfa4d8809aa6d3"

PaymentService paymentService = paymillContext.PaymentService;
paymentService.DeleteAsync("pay_3af44644dd6d25c820a8").Result;

pm.payments.remove("pay_3af44644dd6d25c820a8").then(function(payment) {
	console.log("payment deleted:" + payment.id);
}, function(error) {
	console.log("couldnt remove payment:" + error);
});

Response

{
    "data":[

    ],
    "mode" : "test"
}

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¶

{
    "id":"preauth_0b771c503680c341548e",
    "amount":"4200",
    "currency":"EUR",
    "description":null,
    "status":"closed",
    "livemode":false,
    "created_at":1349950324,
    "updated_at":1349950324,
    "app_id":null,
    "payment":"<Obejct>",
    "client":"<Obejct>",
    "transaction":"<Obejct>"
}

Sub objects

preauthorization.payment returns a payment object for credit card
preauthorization.client returns a client object
preauthorization.transaction returns a transaction 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 or null
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 ...¶

Token

Request

curl <PAYMILL_URL>preauthorizations \
  -u <DEIN_PRIVATE_KEY>: \
  -d "token=098f6bcd4621d373cade4e832627b4f6" \
  -d "amount=4200" \
  -d "currency=EUR"

$preAuth = new Paymill\Models\Request\Preauthorization();
$preAuth->setToken('098f6bcd4621d373cade4e832627b4f6')
        ->setAmount(4200)
        ->setCurrency('EUR');

$response = $request->create($preAuth);

PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
Transaction transaction = preauthorizationService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.preauthorizations.create(
    {
    	token: '098f6bcd4621d373cade4e832627b4f6',
    	amount: 4200,
    	currency: 'EUR'
	},
    function(err, preauthorization) {
        if (err) {
            console.log("Couldn't create the preauthorization record");
            return;
        }
        console.log("preauthorization id " + preauthorization.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
token = '098f6bcd4621d373cade4e832627b4f6'
p = pymill.Pymill(private_key)
preauth = p.preauth(
    amount=100,
    currency="EUR",
    description="example pre-auth",
    token=token
)

Paymill::Preauthorization.create token: "098f6bcd4621d373cade4e832627b4f6",
    amount: 4200, currency: "EUR"

PreauthorizationService preauthorizationService = paymillContext.PreauthorizationService;
Transaction transaction = preauthorizationService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR"
).Result;

pm.preauthorizations.createWithToken("098f6bcd4621d373cade4e832627b4f6", 4200, "EUR").then(function(preauth) {
	console.log("preauth:" + preauth.id);
}, function(error) {
	console.log("couldnt create preauth:" + error);
});

Response

{
    "data":{
        "id":"preauth_e396d56e773f745dfbd3",
        "amount":"4200",
        "currency":"EUR",
        "description":null,
        "status":"closed",
        "livemode":false,
        "created_at":1350324120,
        "updated_at":1350324120,
        "app_id":null,
        "payment""<Obejct>",
        "client":"<Obejct>",
        "transaction":"<Obejct>"
    },
    "mode":"test"
}

Sub objects

preauthorization.payment returns a payment object for credit card
preauthorization.client returns a client object
preauthorization.transaction returns a transaction object

Payment

Request

curl <PAYMILL_URL>preauthorizations \
  -u <DEIN_PRIVATE_KEY>: \
  -d "payment=pay_d43cf0ee969d9847512b" \
  -d "amount=4200" \
  -d "currency=EUR"

$preAuth = new Paymill\Models\Request\Preauthorization();
$preAuth->setPayment('pay_d43cf0ee969d9847512b')
        ->setAmount(4200)
        ->setCurrency('EUR');

$response = $request->create($preAuth);

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6"
);
PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
Transaction transaction = preauthorizationService.createWithPayment(
    payment,
    4200,
    "EUR"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.preauthorizations.create(
    {
    	payment: 'pay_d43cf0ee969d9847512b',
    	amount: 4200,
    	currency: 'EUR'
	},
    function(err, preauthorization) {
        if (err) {
            console.log("Couldn't create the preauthorization record");
            return;
        }
        console.log("preauthorization id " + preauthorization.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
preauth = p.preauth(
    amount=100,
    currency='EUR',
    description='Test Pre-Authorization',
    payment='pay_d43cf0ee969d9847512b'
)

Paymill::Preauthorization.create payment: "pay_d43cf0ee969d9847512b",
    amount: 4200, currency: "EUR"

PaymentService paymentService = paymillContext.PaymentService;
Payment payment = paymentService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6"
).Result;
PreauthorizationService preauthorizationService = paymillContext.PreauthorizationService;
Transaction transaction = preauthorizationService.CreateWithPaymentAsync(
    payment,
    4200,
    "EUR"
).Result;

pm.preauthorizations.createWithPayment("pay_d43cf0ee969d9847512b", 4200, "EUR").then(function(preauth) {
	console.log("preauth:" + preauth.id);
}, function(error) {
	console.log("couldnt create preauth:" + error);
});

Response

{
    "data":{
        "id":"preauth_0b771c503680c341548e",
        "amount":"4200",
        "currency":"EUR",
        "description":null,
        "status":"closed",
        "livemode":false,
        "created_at":1349948920,
        "updated_at":1349948920,
        "app_id":null,
        "payment""<Obejct>",
        "client":"<Obejct>",
        "transaction":"<Obejct>"
    },
    "mode":"test"
}

Sub objects

preauthorization.payment returns a payment object for credit card
preauthorization.client returns a client object
preauthorization.transaction returns a transaction object

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

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¶

curl <PAYMILL_URL>preauthorizations/preauth_31eb90495837447f76b7 \
  -u <DEIN_PRIVATE_KEY>:

$preAuth = new Paymill\Models\Request\Preauthorization();
$preAuth->setId('preauth_31eb90495837447f76b7');

$response = $request->getOne($preAuth);

PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
Preauthorization preauthorization = preauthorizationService.get(
    "preauth_31eb90495837447f76b7"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.preauthorizations.details('preauth_31eb90495837447f76b7',
    function(err, preauthorization) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("preauthorization id " + preauthorization.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
preauth = p.getpreauthdetails(
    preid='preauth_31eb90495837447f76b7'
)

Paymill::Preauthorization.find "preauth_31eb90495837447f76b7"

PreauthorizationService preauthorizationService = paymillContext.PreauthorizationService;
Preauthorization preauthorization = preauthorizationService.GetAsync(
    "preauth_31eb90495837447f76b7"
).Result;

pm.preauthorizations.detail("preauth_31eb90495837447f76b7").then(function(preauth) {
	console.log("preauth:" + preauth.id);
}, function(error) {
	console.log("couldnt get preauths:" + error);
});

Response

{
    "data":{
        "id":"preauth_0b771c503680c341548e",
        "amount":"4200",
        "currency":"EUR",
        "description":null,
        "status":"closed",
        "livemode":false,
        "created_at":1349948920,
        "updated_at":1349948920,
        "app_id":null,
        "payment""<Obejct>",
        "client":"<Obejct>",
        "transaction":"<Obejct>"
    },
    "mode":"test"
}

Sub objects

preauthorization.payment returns a payment object for credit card
preauthorization.client returns a client object
preauthorization.transaction returns a transaction object

Returns data of a specific preauthorization.

Attributes¶

id: string Unique identifier of this preauthorization

Remove `Preauthorizations`¶

curl <PAYMILL_URL>preauthorizations/preauth_31eb90495837447f76b7 \
  -u <DEIN_PRIVATE_KEY>: \
  -X DELETE

$preAuth = new Paymill\Models\Request\Preauthorization();
$preAuth->setId('preauth_31eb90495837447f76b7');

$response = $request->delete($preAuth);

PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
preauthorizationService.delete( "preauth_31eb90495837447f76b7" );

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.preauthorizations.remove('preauth_88a388d9dd48f86c3136',
    function(err, preauthorization) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("deleted the preauthorization");
    }
);

# Not implemented yet

Paymill::Preauthorization.delete "preauth_78ddcedb546909304d43"

PreauthorizationService preauthorizationService = paymillContext.PreauthorizationService;
preauthorizationService.DeleteAsync( "preauth_31eb90495837447f76b7" ).Result;

/* Not implemented */

Response

{
    "data":[

    ],
    "mode" : "test"
}

This function deletes a preauthorization.

Attributes¶

id: string Unique identifier for the preauthorization

List `Preauthorizations`¶

curl <PAYMILL_URL>preauthorizations \
  -u <DEIN_PRIVATE_KEY>:

$preAuth = new Paymill\Models\Request\Preauthorization();

$response = $request->getAll($preAuth);

PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
PaymillList<Preauthorization> preauthorizations = preauthorizationService.list();

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.preauthorizations.list({},
    function(err, preauthorization) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("preauthorization data " + preauthorization.data);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
preauths = p.getpreauth()

Paymill::Preauthorization.all

PreauthorizationService preauthorizationService = paymillContext.PreauthorizationService;
PaymillList<Preauthorization> preauthorizations = preauthorizationService.ListAsync().Result;

pm.preauthorizations.list().then(function(pmlist) {
	console.log(pmlist.items.length + " preauths from total of " + pmlist.count);
}, function(error) {
	console.log("couldnt list preauths:" + error);
});

Response

{
    "data" : [
        {
            "id":"preauth_0b771c503680c341548e",
            "amount":"4200",
            "currency":"EUR",
            "description":null,
            "status":"closed",
            "livemode":false,
            "created_at":1349948920,
            "updated_at":1349948920,
            "app_id":null,
            "payment""<Obejct>",
            "client":"<Obejct>",
            "transaction":"<Obejct>"
        }
    ],
    "data_count" : "1",
    "mode" : "test"
}

Sub objects

preauthorization.payment returns a payment object for credit card
preauthorization.client returns a client object
preauthorization.transaction returns a transaction object

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¶

{
    "id" : "tran_54645bcb98ba7acfe204",
    "amount" : "4200",
    "origin_amount" : 4200,
    "status" : "closed",
    "description" : null,
    "livemode" : false,
    "is_fraud" : false,
    "refunds" : null,
    "currency" : "EUR",
    "created_at" : 1349946151,
    "updated_at" : 1349946151,
    "response_code" : 20000,
    "short_id" : "0000.1212.3434",
    "invoices" : [],
    "payment" : "<Object>",
    "client" : "<Object>",
    "preauthorization" : null,
    "fees" : [],
    "app_id" : null
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization 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 or null
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 ...¶

Payment

Request

curl <PAYMILL_URL>transactions \
  -u <DEIN_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "payment=pay_2f82a672574647cd911d" \
  -d "description=Test Transaction"

$transaction = new Paymill\Models\Request\Transaction();
$transaction->setAmount(4200) // e.g. "4200" for 42.00 EUR
            ->setCurrency('EUR')
            ->setPayment('pay_2f82a672574647cd911d')
            ->setDescription('Test Transaction');

$response = $request->create($transaction);

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6"
);
TransactionService transactionService = paymillContext.getTransactionService();
Transaction transaction = transactionService.createWithToken(
    payment,
    4200,
    "EUR",
    "Test Transaction"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.transactions.create(
    {
    	amount: 4200,
    	currency: 'EUR',
    	payment: 'pay_a818b847db6ce5ff636f'
    	description: 'Test Transaction'
	},
    function(err, transaction) {
        if (err) {
            console.log("Couldn't create the transaction record");
            return;
        }
        console.log("transaction id " + transaction.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
transaction = p.transact(
    amount=4200,
    currency='EUR',
    description='Test Transaction',
    payment='pay_2f82a672574647cd911d'
)

Paymill::Transaction.create amount: 4200, currency: "EUR",
    payment: "pay_2f82a672574647cd911d",
    description: "Test Transaction"

PaymentService paymentService = paymillContext.PaymentService;
Payment payment = paymentService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6"
).Result;
TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithTokenAsync(
    payment,
    4200,
    "EUR",
    "Test Transaction"
).Result;

pm.transactions.createWithPayment("pay_2f82a672574647cd911d", 4200, "EUR", "Test Transaction").then(function(transaction) {
	console.log("transaction:" + transaction.id);
}, function(error) {
	console.log("couldnt create transaction:" + error);
});

Response

{
    "data" : {
        "id" : "tran_1f42e10cf14301067332",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : null,
        "livemode" : false,
        "refunds" : null,
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "is_fraud" : false,
        "invoices" : [],
        "payment" : "<Object>",
        "client" : "<Object>",
        "preauthorization" : null,
        "fees" : [],
        "app_id" : null
    },
    "mode" : "test"
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization object

Token

When using a credit card or direct debit account for the first time, you can use a token. For the second transaction and on, use the payment object created for this token. Tokens are not reusable

Request

curl <PAYMILL_URL>transactions \
  -u <DEIN_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "token=098f6bcd4621d373cade4e832627b4f6" \
  -d "description=Test Transaction"

$transaction = new Paymill\Models\Request\Transaction();
$transaction->setAmount(4200) // e.g. "4200" for 42.00 EUR
            ->setCurrency('EUR')
            ->setToken('098f6bcd4621d373cade4e832627b4f6')
            ->setDescription('Test Transaction');

$response = $request->create($transaction);

TransactionService transactionService = paymillContext.getTransactionService();
Transaction transaction = transactionService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    "Test Transaction"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.transactions.create(
    {
        amount: 4200,
        currency: 'EUR',
        token: '098f6bcd4621d373cade4e832627b4f6',
        description: 'Test Transaction'
    },
    function(err, transaction) {
        if (err) {
            console.log("Couldn't create the transaction record");
            return;
        }
        console.log("transaction id " + transaction.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
transaction = p.transact(
    amount=4200,
    currency='EUR',
    description='Test Transaction',
    token='098f6bcd4621d373cade4e832627b4f6'
)

Paymill::Transaction.create amount: 4200, currency: "EUR",
    token: "098f6bcd4621d373cade4e832627b4f6",
    description: "Test Transaction"

TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    "Test Transaction"
).Result;

pm.transactions.createWithToken("098f6bcd4621d373cade4e832627b4f6", 4200, "EUR", "Test Transaction").then(function(transaction) {
	console.log("transaction:" + transaction.id);
}, function(error) {
	console.log("couldnt create transaction:" + error);
});

Response

{
    "data" : {
        "id" : "tran_b3692e8e063900d27a40",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : null,
        "livemode" : false,
        "refunds" : null,
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "is_fraud" : false,
        "invoices" : [],
        "payment" : "<Object>",
        "client" : "<Object>",
        "preauthorization" : null,
        "fees": [],
        "app_id" : null
    },
    "mode" : "test"
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization object

Client & Payment

Request

curl <PAYMILL_URL>transactions \
  -u <DEIN_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "client=client_c781b1d2f7f0f664b4d9" \
  -d "payment=pay_a818b847db6ce5ff636f" \
  -d "description=Test Transaction"

$transaction = new Paymill\Models\Request\Transaction();
$transaction->setAmount(4200) // e.g. "4200" for 42.00 EUR
            ->setCurrency('EUR')
            ->setClient('client_c781b1d2f7f0f664b4d9')
            ->setPayment('pay_2f82a672574647cd911d')
            ->setDescription('Test Transaction');

$response = $request->create($transaction);

TransactionService transactionService = paymillContext.getTransactionService();
Transaction transaction = transactionService.createWithPaymentAndClient(
    "pay_a818b847db6ce5ff636f",
    "client_c781b1d2f7f0f664b4d9",
    4200,
    "EUR"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.transactions.create(
    {
    	amount: 4200,
    	currency: 'EUR',
    	client: 'client_c781b1d2f7f0f664b4d9',
    	payment: 'pay_a818b847db6ce5ff636f'
    	description: 'Test Transaction'
	},
    function(err, transaction) {
        if (err) {
            console.log("Couldn't create the transaction record");
            return;
        }
        console.log("transaction id " + transaction.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
transaction = p.transact(
    amount=4200,
    currency='EUR',
    description='Test Transaction',
    client='client_c781b1d2f7f0f664b4d9',
    payment='pay_a818b847db6ce5ff636f'
)

Paymill::Transaction.create amount: 4200, currency: "EUR",
    client: "client_c781b1d2f7f0f664b4d9",
    payment: "pay_2f82a672574647cd911d",
    description: "Test Transaction"

TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithPaymentAndClientAsync(
    "pay_a818b847db6ce5ff636f",
    "client_c781b1d2f7f0f664b4d9",
    4200,
    "EUR"
).Result;

pm.transactions.createWithPayment("pay_2f82a672574647cd911d", 4200, "EUR", "Test Transaction", "client_c781b1d2f7f0f664b4d9").then(function(transaction) {
	console.log("transaction:" + transaction.id);
}, function(error) {
	console.log("couldnt create transaction:" + error);
});

Response

{
    "data" : {
        "id" : "tran_663dada2ffd9b47bd1bf",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : null,
        "livemode" : false,
        "refunds" : null,
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "is_fraud" : false,
        "invoices" : [],
        "payment" : "<Object>",
        "client" : "<Object>",
        "preauthorization" : null,
        "fees": [],
        "app_id" : null
    },
    "mode" : "test"
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization object

Preauthorization

Request

curl <PAYMILL_URL>transactions \
  -u <DEIN_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "preauthorization=preauth_ec54f67e52e92051bd65" \
  -d "description=Test Transaction"

$transaction = new Paymill\Models\Request\Transaction();
$transaction->setAmount(4200) // e.g. "4200" for 42.00 EUR
            ->setCurrency('EUR')
            ->setPreauthorization('preauth_ec54f67e52e92051bd65')
            ->setDescription('Test Transaction');

$response = $request->create($transaction);

PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
Preauthorization preauthorization = preauthorizationService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR"
).getPreauthorization();
TransactionService transactionService = paymillContext.getTransactionService();
Transaction transaction = this.transactionService.createWithPreauthorization(
    preauthorization,
    4200,
    "EUR"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.transactions.create(
    {
    	amount: 4200,
    	currency: 'EUR',
    	preauthorization: 'preauth_ec54f67e52e92051bd65'
    	description: 'Test Transaction'
	},
    function(err, transaction) {
        if (err) {
            console.log("Couldn't create the transaction record");
            return;
        }
        console.log("transaction id " + transaction.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
    transaction = p.transact(
    amount=4200,
    currency='EUR',
    description='Test Transaction',
    preauth='preauth_ec54f67e52e92051bd65'
)

Paymill::Transaction.create amount: 4200, currency: "EUR",
    preauthorization: "preauth_ec54f67e52e92051bd65",
    description: "Test Transaction"

PreauthorizationService preauthorizationService = paymillContext.PreauthorizationService;
Preauthorization preauthorization = preauthorizationService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR"
).Result;

TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithPreauthorizationAsync(
    preauthorization,
    4200,
    "EUR"
).Result;

pm.transactions.createWithPreauthorization("preauth_ec54f67e52e92051bd65", 4200, "EUR", "Test Transaction").then(function(transaction) {
	console.log("transaction:" + transaction.id);
}, function(error) {
	console.log("couldnt create transaction:" + error);
});

Response

{
    "data" : {
        "id" : "tran_ca3e7d41fb16d0157a99",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : null,
        "livemode" : false,
        "refunds" : null,
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "is_fraud" : false,
        "invoices": [],
        "payment" : "<Object>",
        "client" : "<Object>",
        "preauthorization" : "<Object>",
        "fees": [],
        "app_id" : null
    },
    "mode" : "test"
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization object

App fee

Request

curl <PAYMILL_URL>transactions \
  -u <DEIN_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "token=098f6bcd4621d373cade4e832627b4f6" \
  -d "description=Test Transaction" \
  -d "fee_amount=420" \
  -d "fee_payment=pay_3af44644dd6d25c820a8" \
  -d "fee_currency=EUR"

$transaction = new Paymill\Models\Request\Transaction();
$transaction->setAmount(4200) // e.g. "4200" for 42.00 EUR
            ->setCurrency('EUR')
            ->setToken('098f6bcd4621d373cade4e832627b4f6')
            ->setDescription('Test Transaction')
            ->setFeeAmount(420)
            ->setFeePayment('pay_3af44644dd6d25c820a8')
            ->setFeeCurrency('EUR');

$response = $request->create($transaction);

Fee fee = new Fee();
fee.setAmount( 420 );
fee.setPayment( "pay_3af44644dd6d25c820a8" );
TransactionService transactionService = paymillContext.getTransactionService();
Transaction transaction = transactionService.createWithTokenAndFee(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    fee
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.transactions.create(
    {
       amount: 4200,       // e.g. "4200" for 42.00 EUR
       currency: 'EUR',
       token: '098f6bcd4621d373cade4e832627b4f6',
       description: 'Test Transaction',
       fee_amount: 420,    // e.g. "420" for 4.20 EUR
       fee_payment: 'pay_3af44644dd6d25c820a8'
	},
    function(err, transaction) {
        if (err) {
            console.log("Couldn't create the transaction record");
            return;
        }
        console.log("transaction id " + transaction.data.id);
    }
);

# Not implemented yet

Paymill::Transaction.create amount: 4200, currency: "EUR",
    token: "098f6bcd4621d373cade4e832627b4f6",
    description: "Test Transaction",
    fee_amount: 420,
    fee_payment: "pay_3af44644dd6d25c820a8",
    fee_currency: "EUR"

Fee fee = new Fee();
fee.Amount =  420;
fee.Payment = "pay_3af44644dd6d25c820a8";
TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithTokenAndFeeAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    fee
).Result;

pm.transactions.createWithToken("098f6bcd4621d373cade4e832627b4f6", 4200, "EUR", "Test Transaction", null, 420, "pay_3af44644dd6d25c820a8").then(function(transaction) {
	console.log("transaction:" + transaction.id);
}, function(error) {
	console.log("couldnt create transaction:" + error);
});

Response

{
    "data" : {
        "id" : "tran_ca3e7d41fb16d0157a99",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : null,
        "livemode" : false,
        "refunds" : null,
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "invoices": [],
        "payment" : "<Object>",
        "client" : "<Object>",
        "preauthorization" : "<Object>",
        "fees" : [
          {
            "type" : "application",
            "application" : "app_1d70acbf80c8c35ce83680715c06be0",
            "payment" : "pay_098f6bcd4621d373cade4e832627b4f6",
            "amount" : 420,
            "currency": "EUR",
            "billed_at": null
          }
        ],
        "app_id" : null
    },
    "mode" : "test"
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization object

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¶

curl <PAYMILL_URL>transactions/tran_023d3b5769321c649435 \
  -u <DEIN_PRIVATE_KEY>:

$transaction = new Paymill\Models\Request\Transaction();
$transaction->setId('tran_023d3b5769321c649435');

$response = $request->getOne($transaction);

TransactionService transactionService = paymillContext.getTransactionService();
Transaction transaction = transactionService.get("tran_023d3b5769321c649435");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.transactions.details('tran_023d3b5769321c649435',
    function(err, transaction) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("transaction id " + transaction.data.id);
    }
);

curl <PAYMILL_URL>transactions/tran_023d3b5769321c649435 \
  -u <DEIN_PRIVATE_KEY>:

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
transaction = p.gettransdetails('tran_023d3b5769321c649435')

Paymill::Transaction.find "tran_023d3b5769321c649435"

TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.GetAsync("tran_023d3b5769321c649435").Result;

pm.transactions.detail("tran_023d3b5769321c649435").then(function(transaction) {
	console.log("transaction:" + transaction.id);
}, function(error) {
	console.log("couldnt get transaction:" + error);
});

Response

{
    "data" : {
        "id" : "tran_023d3b5769321c649435",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : null,
        "livemode" : false,
        "refunds" : null,
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "is_fraud" : false,
        "invoices": [],
        "payment" : "<Object>",
        "client" : "<Object>",
        "preauthorization" : null,
        "fees" : [],
        "app_id" : null
    },
    "mode" : "test"
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization object

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`¶

curl <PAYMILL_URL>transactions/tran_023d3b5769321c649435 \
  -u <DEIN_PRIVATE_KEY>:  \
  -d "description=My updated transaction description" -X PUT

$transaction = new Paymill\Models\Request\Transaction();
$transaction->setId('tran_023d3b5769321c649435')
            ->setDescription('My updated transaction description');

$response = $request->update($transaction);

TransactionService transactionService = paymillContext.getTransactionService();
Transaction transaction = transactionService.get("tran_023d3b5769321c649435");
transaction.setDescription("My updated transaction description");
transactionService.update( transaction );

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.transactions.update('tran_023d3b5769321c649435',
  {
      description: 'My updated transaction description'
  },
    function(err, transaction) {
        if (err) {
            console.log("Couldn't update the transaction record");
            return;
        }
        console.log("transaction id " + transaction.data.id);
    }
);

# Not implemented yet

Paymill::Transaction.update_attributes "tran_023d3b5769321c649435",
    description: "My updated transaction description"
# or
transaction = Paymill::Transaction.create amount: 4200, currency: "EUR",
    token: "098f6bcd4621d373cade4e832627b4f6",
    description: "Test Transaction"
transaction.update_attributes description: "My updated transaction description"

TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.GetAsync("tran_023d3b5769321c649435").Result;
transaction.Description = "My updated transaction description";
transactionService.UpdateAsync(transaction).Result;

pm.transactions.detail("tran_023d3b5769321c649435").then(function(transaction) {
	transaction.description = "My updated transaction description";
	return pm.transactions.update(transaction);
}).then(function(updatedTransaction) {
	console.log("updated transaction:" + updatedTransaction.description);
}, function(error) {
	console.log("couldnt update transaction:" + error);
});

Response

{
    "data" : {
        "id" : "tran_023d3b5769321c649435",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : "My updated transaction description",
        "livemode" : false,
        "refunds" : null,
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "status" : "closed",
        "is_fraud" : false,
        "short_id" : "0000.1212.3434",
        "fees" : [],
        "invoices" : [],
        "payment" : "<Object>",
        "client" : "<Object>",
        "preauthorization" : null,
        "app_id" : null
    },
    "mode" : "test"
}

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`¶

curl <PAYMILL_URL>transactions \
  -u <DEIN_PRIVATE_KEY>:

$transaction = new Paymill\Models\Request\Transaction();

$response = $request->getAll($transaction);

TransactionService transactionService = paymillContext.getTransactionService();
PaymillList<Transaction> transactions = transactionService.list();

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.transactions.list({},
    function(err, transaction) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("transaction data " + transaction.data);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
transactions = p.gettrans()

Paymill::Transaction.all

TransactionService transactionService = paymillContext.TransactionService;
PaymillList<Transaction> transactions = transactionService.ListAsync().Result;

pm.transactions.list().then(function(pmlist) {
	console.log(pmlist.items.length + " transactions from total of " + pmlist.count);
}, function(error) {
	console.log("couldnt list transactions:" + error);
});

Response

{
    "data" : [
        {
            "id" : "tran_03bb8f63d5278f723ced",
            "amount" : "4200",
            "origin_amount" : 4200,
            "status" : "closed",
            "description" : "ShoppingcartID 873242",
            "livemode" : false,
            "refunds" : null,
            "currency" : "EUR",
            "created_at" : 1349946151,
            "updated_at" : 1349946151,
            "response_code" : 20000,
            "short_id" : "0000.1212.3434",
            "is_fraud" : false,
            "invoices" : [],
            "payment" : "<Object>",
            "client" : "<Object>",
            "preauthorization" : null,
            "fees" : [],
            "app_id" : null
        },
        {
            "id" : "tran_5e3105d4c2f34fe9d1f",
            "amount" : "5699",
            "origin_amount" : 5699,
            "status" : "closed",
            "description" : "ShoppingcartID 873243",
            "livemode" : false,
            "refunds" : null,
            "currency" : "EUR",
            "created_at" : 1349953847,
            "updated_at" : 1349953847,
            "response_code" : 20000,
            "short_id" : "0000.1212.3435",
            "is_fraud" : false,
            "invoices" : [],
            "payment" : "<Object>",
            "client" : "<Object>",
            "preauthorization" : null,
            "fees" : [],
            "app_id" : null
        }
    ],
    "data_count" : "2",
    "mode" : "test"
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization object

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¶

curl <PAYMILL_URL>refunds/tran_023d3b5769321c649435 \
  -u <DEIN_PRIVATE_KEY>: \
  -d "amount=4200"

$refund = new Paymill\Models\Request\Refund();
$refund->setId('tran_023d3b5769321c649435')
       ->setAmount(4200) // e.g. "4200" for 42.00 EUR
       ->setDescription('Sample Description');

$response = $request->create($refund);

TransactionService = paymillContext.getTransactionService();
Transaction transaction = this.transactionService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    "For refund"
);
RefundService = paymillContext.getRefundService();
Refund refund = refundService.refundTransaction( 
    transaction, 
    1000, 
    "Sample Description" 
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.refunds.refund('tran_023d3b5769321c649435', 4200, "",
    function(err, refund) {
        if (err) {
            console.log("Couldn't create the refund record");
            return;
        }
        console.log("refund id " + refund.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
refund = p.refund(
    tranid='tran_023d3b5769321c649435',
    amount=100,
    description='Test Refund'
)

Paymill::Refund.create id: "tran_f5bc741dc3809ad3c62fd255e60c",
    amount: 4200

TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    "For refund"
).Result;
RefundService = paymillContext.RefundService;
Refund refund = refundService.RefundTransactionAsync(
    transaction,
    1000,
    "Sample Description"
).Result;

pm.transactions.refund("result", 4200, "Sample Description").then(function(refund) {
	console.log("refund:" + refund.id);
}, function(error) {
	console.log("couldnt refund transaction:" + error);
});

Response

{
    "data" : {
        "id" : "refund_70392dc6a734a8233130",
        "amount" : "010",
        "status" : "refunded",
        "description" : null,
        "livemode" : false,
        "created_at" : 1365154751,
        "updated_at" : 1365154751,
        "response_code" : 20000,
        "transaction" : "<Object>",
        "app_id" :  null
    },
    "mode" : "test"
}

Sub objects

transaction.refunds returns refund objects
transaction.payment returns a payment object for credit card
transaction.client returns a client object
transaction.preauthorization returns a preauthorization object

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¶

curl <PAYMILL_URL>refunds/refund_87bc404a95d5ce616049 \
  -u <DEIN_PRIVATE_KEY>:

$refund = new Paymill\Models\Request\Refund();
$refund->setId('refund_773ab6f9cd03428953c9');

$response = $request->getOne($refund);

RefundService = paymillContext.getRefundService();
Refund refund = refundService.get("refund_773ab6f9cd03428953c9");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.refunds.details('refund_87bc404a95d5ce616049',
    function(err, refund) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("refund id " + refund.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
refund = p.getrefdetails('refund_773ab6f9cd03428953c9')

Paymill::Refund.find "refund_87bc404a95d5ce616049"

RefundService refundService = paymillContext.RefundService();
Refund refund = refundService.GetAsync("refund_773ab6f9cd03428953c9").Result;

pm.refunds.detail("refund_773ab6f9cd03428953c9").then(function(refund) {
	console.log("refund:" + refund.id);
}, function(error) {
	console.log("couldnt get refund:" + error);
});

Response

{
    "data" : {
        "id" : "refund_87bc404a95d5ce616049",
        "amount" : "042",
        "status" : "refunded",
        "description" : null,
        "livemode" : false,
        "created_at" : 1349947042,
        "updated_at" : 1349947042,
        "response_code" : 20000,
        "transaction" : "<Object>",
        "app_id" : null
    },
    "mode" : "test"
}

Sub objects

refund.transaction returns a transaction object

Returns detailed informations of a specific refund.

List `Refunds`¶

curl <PAYMILL_URL>refunds \
  -u <DEIN_PRIVATE_KEY>:

$refund = new Paymill\Models\Request\Refund();

$response = $request->getAll($refund);

RefundService = paymillContext.getRefundService();
PaymillList<Refund> refunds = refundService.list();

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.refunds.list({},
    function(err, refund) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("refund data " + refund.data);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
refunds = p.getrefs()

Paymill::Refund.all

RefundService refundService = paymillContext.RefundService;
PaymillList<Refund> refunds = refundService.ListAsync;

pm.refunds.list().then(function(pmlist) {
	console.log(pmlist.items.length + " refunds from total of " + pmlist.count);
}, function(error) {
	console.log("couldnt list transactions:" + error);
});

Response

{
    "data" : [
        {
            "id" : "refund_87bc404a95d5ce616049",
            "amount" : "042",
            "status" : "refunded",
            "description" : null,
            "livemode" : false,
            "created_at" : 1349947042,
            "updated_at" : 1349947042,
            "response_code" : 20000,
            "transaction" : "<Object>",
            "app_id" : null
        }
    ],
    "data_count" : "1",
    "mode" : "test"
}

Sub objects

refund.transaction returns a transaction object

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`¶

curl <PAYMILL_URL>clients \
  -u <DEIN_PRIVATE_KEY>: \
  -d "[email protected]" \
  -d "description=Lovely Client"

$client = new Paymill\Models\Request\Client();
$client->setEmail('[email protected]')
       ->setDescription('Lovely Client')

$response = $request->create($client);

ClientService clientService = paymillContext.getClientService();
Client client = clientService.createWithEmailAndDescription(
    "[email protected]",
    "Lovely Client"
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.clients.create(
    {
    	email: '[email protected]',
        description: 'Lovely Client'
	},
    function(err, client) {
        if (err) {
            console.log("Couldn't create the client record");
            return;
        }
        console.log("client id " + client.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
client = p.newclient(
  email='[email protected]',
  description='Lovely Client'
)

client = Paymill::Client.create email: "[email protected]",
    description: "Lovely Client"

ClientService clientService = paymillContext.ClientService;
Client client = clientService.CreateWithEmailAndDescriptionAsync(
    "[email protected]",
    "Lovely Client"
).Result;

pm.clients.create("[email protected]", "Lovely Client").then(function(client) {
    console.log("client:" + client.id);
}, function(error) {
    console.log("couldnt get client:" + error);
});

Response

{
    "data" : {
        "id"           : "client_88a388d9dd48f86c3136",
        "email"        : "[email protected]",
        "description"  : "Lovely Client",
        "created_at"   : 1342438695,
        "updated_at"   : 1342438695,
        "payment"      : "[ <Object>, ... ]",
        "subscription" : "<Object>",
        "app_id"       : null
    },
    "mode" : "test"
}

Sub objects

client.payment returns payment objects for credit card or direct debit
client.subscription returns a subscription object

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¶

curl <PAYMILL_URL>clients/client_88a388d9dd48f86c3136 \
  -u <DEIN_PRIVATE_KEY>:

$client = new Paymill\Models\Request\Client();
$client->setId('client_88a388d9dd48f86c3136');

$response = $request->getOne($client);

ClientService clientService = paymillContext.getClientService();
Client client = clientService.get("client_88a388d9dd48f86c3136");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.clients.details('client_88a388d9dd48f86c3136',
    function(err, client) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("client id " + client.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
client = p.getclientdetails(cid='client_88a388d9dd48f86c3136')

Paymill::Client.find "client_88a388d9dd48f86c3136"

ClientService clientService = paymillContext.ClientService;
Client client = clientService.GetAsync("client_88a388d9dd48f86c3136").Result;

pm.clients.detail("client_88a388d9dd48f86c3136").then(function(client) {
	console.log("client:" + client.id);
}, function(error) {
	console.log("couldnt get client:" + error);
});

Response

{
    "data" : {
        "id"           : "client_88a388d9dd48f86c3136",
        "email"        : "[email protected]",
        "description"  : "Lovely Client",
        "created_at"   : 1342438695,
        "updated_at"   : 1342438695,
        "payment"      : "[ <Object>, ... ] or null",
        "subscription" : "<Object>",
        "app_id"       : null
    },
    "mode" : "test"
}

Sub objects

client.payment returns payment objects for credit card or direct debit
client.subscription returns a subscription object

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`¶

curl <PAYMILL_URL>clients/client_88a388d9dd48f86c3136 \
  -u <DEIN_PRIVATE_KEY>: \
  -d "[email protected]" \
  -d "description=My Lovely Client" \
  -X PUT

$client = new Paymill\Models\Request\Client();
$client->setId('client_88a388d9dd48f86c3136')
       ->setEmail('[email protected]')
       ->setDescription('Updated Client');

$response = $request->update($client);

ClientService clientService = paymillContext.getClientService();
Client client = clientService.get("client_88a388d9dd48f86c3136");
client.setDescription("My Lovely Client");
clientService.update( client );

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.clients.update('client_88a388d9dd48f86c3136',
    {
    	email: '[email protected]',
        description: 'Most awesome client EVAR'
	},
    function(err, client) {
        if (err) {
            console.log("Couldn't update the client record");
            return;
        }
        console.log("client id " + client.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
client = p.updateclient(
    cid=self.client['data']['id'],
    email='[email protected]',
    description='Most awesome client EVAR'
)

Paymill::Client.update_attributes "client_88a388d9dd48f86c3136",
    description: "My Lovely Client"
# or
client = Paymill::Client.create email: "[email protected]",
    description: "Lovely Client"
client.update_attributes description: "My Lovely Client"

ClientService clientService = paymillContext.ClientService;
Client client = clientService.GetAsync("client_88a388d9dd48f86c3136").Result;
client.Description = "My Lovely Client";
clientService.UpdateAsync( client ).Result;

pm.clients.detail("client_88a388d9dd48f86c3136").then(function(client) {
	client.description = "My Updated Lovely Client";
	return pm.clients.update(client);
}).then(function(updatedClient) {
	console.log("updated client:" + updatedClient.description);
}, function(error) {
	console.log("couldnt update client:" + error);
});

Response

{
    "data" : {
        "id"           : "client_88a388d9dd48f86c3136",
        "email"        : "[email protected]",
        "description"  : "My Lovely Client",
        "created_at"   : 1342438695,
        "updated_at"   : 1342439774,
        "payment"      : "[ <Object>, ... ] or null",
        "subscription" : "<Object>",
        "app_id"       : null
    },
    "mode" : "test"
}

Sub objects

client.payment returns payment objects for credit card or direct debit
client.subscription returns a subscription object

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`¶

curl <PAYMILL_URL>clients/client_88a388d9dd48f86c3136 \
  -u <DEIN_PRIVATE_KEY>: \
  -X DELETE

$client = new Paymill\Models\Request\Client();
$client->setId('client_88a388d9dd48f86c3136');

$response = $request->delete($client);

ClientService clientService = paymillContext.getClientService();
clientService.delete("client_88a388d9dd48f86c3136");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.clients.remove('client_88a388d9dd48f86c3136',
    function(err, client) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("deleted the client");
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
response = p.delclient('client_88a388d9dd48f86c3136')

Paymill::Client.delete "client_88a388d9dd48f86c3136"

ClientService clientService = paymillContext.ClientService;
clientService.DeleteAsync("client_88a388d9dd48f86c3136").Result;

pm.clients.remove("client_88a388d9dd48f86c3136").then(function(client) {
	console.log("deleted client:" + client.id);
}, function(error) {
	console.log("couldnt get transaction:" + error);
});

Response

{
    "data": {
        "id"           : "client_88a388d9dd48f86c3136",
        "email"        : "[email protected]",
        "description"  : "Lovely Client",
        "created_at"   : 1342438695,
        "updated_at"   : 1342438695,
        "payment"      : "[ <Object>, ... ] or null",
        "subscription" : "<Object>",
        "app_id"       : null
    },
    "mode" : "test"
}

Sub objects

client.payment returns payment objects for credit card or direct debit
client.subscription returns a subscription object

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

Attributes¶

id: string Unique identifier for the client

List `Clients`¶

curl <PAYMILL_URL>clients \
  -u <DEIN_PRIVATE_KEY>:

$client = new Paymill\Models\Request\Client();

$response = $request->getAll($client);

 ClientService clientService = paymillContext.getClientService();
 PaymillList<Client> clients = clientService.list();

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.clients.list({},
    function(err, client) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("client data " + payments.data);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
clients = p.getclients()

Paymill::Client.all

ClientService clientService = paymillContext.ClientService;
PaymillList<Client> clients = clientService.ListAsync().Result;

pm.clients.list().then(function(pmlist) {
	console.log(pmlist.items.length + " clients from total of " + pmlist.count);
}, function(error) {
	console.log("couldnt list clients:" + error);
});

Response

{
    "data" : [
        {
            "id"           : "client_bc798246e32ce7e66dbe",
            "email"        : null,
            "description"  : null,
            "created_at"   : 1342427064,
            "updated_at"   : 1342427064,
            "payment"      : "[ <Object>, ... ] or null",
            "subscription" : "<Object>",
            "app_id"       : null
        }
    ],
    "data_count" : "1",
    "mode" : "test"
}

Sub objects

client.payment returns payment objects for credit card or direct debit
client.subscription returns a subscription object

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 Define an optional trial period in number of days
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`¶

curl <PAYMILL_URL>offers \
  -u <DEIN_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "interval=1 MONTH" \
  -d "name=Test Offer"

$offer = new Paymill\Models\Request\Offer();
$offer->setAmount(4200)
      ->setCurrency('EUR')
      ->setInterval('1 MONTH')
      ->setName('Test Offer');

$response = $request->create($offer);

OfferService offerService = paymillContext.getOfferService();
Offer offer = offerService.create("4200", "EUR", "1 MONTH", "Superabo", 30);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.offers.create(
    {
    	amount: 4200,
        currency: 'EUR',
        interval: 'month',
        name: 'Test offer'
	},
    function(err, offer) {
        if (err) {
            console.log("Couldn't create the offer record");
            return;
        }
        console.log("offer id " + offer.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
offer = p.newoffer(
    amount=100,
    interval='month',
    currency='EUR',
    name='Test Offer'
)

Paymill::Offer.create amount: 4200, currency: "EUR",
    interval: "1 MONTH", name: "Test Offer"

OfferService offerService = paymillContext.OfferService;
Offer offer = offerService.CreateAsync("4200", "EUR", "1 MONTH", "Superabo", 30).Result;

pm.offers.create(4200, "EUR", new pm.OfferInterval(2, pm.OfferInterval.Period.WEEK), "Test Offer").then(function(offer) {
	console.log("offer:" + offer.id);
}, function(error) {
	console.log("couldnt get client:" + error);
});

Response

{
    "data" : {
        "id" : "offer_40237e20a7d5a231d99b",
        "name" : "Nerd Special",
        "amount" : "4200",
        "currency": "EUR",
        "interval" : "1 WEEK",
        "trial_period_days" : 0,
        "created_at" : 1341935129,
        "updated_at" : 1341935129,
        "subscription_count": {
            "active": "3",
            "inactive": 0
        },
        "app_id": null
    },
    "mode" : "test"
}

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 Define an optional trial period in number of days

`Offer` Details¶

curl <PAYMILL_URL>offers/offer_40237e20a7d5a231d99b \
  -u <DEIN_PRIVATE_KEY>: \

$offer = new Paymill\Models\Request\Offer();
$offer->setId('offer_40237e20a7d5a231d99b');

$response = $request->getOne($offer);

OfferService offerService = paymillContext.getOfferService();
Offer offer = offerService.get("offer_40237e20a7d5a231d99b");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.offers.details('offer_40237e20a7d5a231d99b',
    function(err, offer) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("offer id " + offer.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
client = p.getofferdetails(oid='offer_40237e20a7d5a231d99b')

Paymill::Offer.find "offer_40237e20a7d5a231d99b"

OfferService offerService = paymillContext.OfferService;
Offer offer = offerService.GetAsync("offer_40237e20a7d5a231d99b").Result;

pm.offers.detail("offer_40237e20a7d5a231d99b").then(function(offer) {
	console.log("offers:" + offer.id);
}, function(error) {
	console.log("couldnt get offer:" + error);
});

Response

{
    "data": {
        "id" : "offer_40237e20a7d5a231d99b",
        "name" : "Nerd Special",
        "amount" : 4200,
        "currency": "EUR",
        "interval" : "1 WEEK",
        "trial_period_days" : 0,
        "created_at" : 1341935129,
        "updated_at" : 1341935129,
        "subscription_count": {
            "active": 3,
            "inactive": 0
        },
        "app_id": null
    },
    "mode" : "test"
}

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

Attributes¶

id: string Unique identifier for the offer

Update `Offer`¶

curl <PAYMILL_URL>offers/offer_40237e20a7d5a231d99b \
  -u <DEIN_PRIVATE_KEY>: \
  -d "name=Extended Offer" \
  -d "interval=1 MONTH" \
  -d "amount=3333" \
  -d "currency=USD" \
  -d "trial_period_days=33" \
  -d "update_subscriptions=true" \
  -X PUT

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

Response

{
    "data" : {
        "id" : "offer_40237e20a7d5a231d99b",
        "name" : "Extended Special",
        "amount" : 3333,
        "currency": "USD",
        "interval" : "1 MONTH",
        "trial_period_days" : 0,
        "created_at" : 1341935129,
        "updated_at" : 1341938129,
        "subscription_count": {
            "active": "3",
            "inactive": 0
        },
        "app_id": null
    },
    "mode" : "test"
}

Updates the offer. With the update_subscriptions attribute all related subscriptions could be updated too.

Attributes¶

id: string Unique identifier for the offer
name: string Your name for this offer (optional)
interval: string Defining how often the client should be charged. Format: number DAY|WEEK|MONTH|YEAR (optional)
amount: string Your amount of the offer in cents (optional)
currency: string ISO 4217 formatted currency code (optional)
trial_period_days: int Your trial period in number of days (optional)
update_subscriptions: boolean Definition, if all related subscriptions also should be updated.

Remove `Offer`¶

curl <PAYMILL_URL>offers/offer_40237e20a7d5a231d99b \
  -u <DEIN_PRIVATE_KEY>: \
  -d "remove_with_subscriptions=false" \
  -X DELETE

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

Response

{
    "data":[

    ],
    "mode" : "test"
}

You only can delete an offer and decide, if all related subscriptions also should be deleted or not.

Attributes¶

id: string Unique identifier for the offer
remove_with_subscriptions: boolean Definition if all related subscriptions also should be deleted.

List `Offers`¶

curl <PAYMILL_URL>offers \
  -u <DEIN_PRIVATE_KEY>:

$offer = new Paymill\Models\Request\Offer();

$response = $request->getAll($offer);

OfferService offerService = paymillContext.getOfferService();
PaymillList<Offer> offers = offerService.list();

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.offers.list({},
    function(err, offer) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("offer data " + offer.data);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
offers = p.getoffers()

Paymill::Offer.all

OfferService offerService = paymillContext.OfferService;
PaymillList<Offer> offers = offerService.ListAsync().Result;

pm.offers.list().then(function(pmlist) {
	console.log(pmlist.items.length + " offers from total of " + pmlist.count);
}, function(error) {
	console.log("couldnt list offers:" + error);
});

Response

{
    "data" : [
        {
            "id" : "offer_40237e20a7d5a231d99b",
            "name" : "Nerd Special",
            "amount" : 4200,
            "currency": "EUR",
            "interval" : "1 WEEK",
            "trial_period_days" : 0,
            "created_at" : 1341935129,
            "updated_at" : 1341935129,
            "subscription_count": {
                "active": "3",
                "inactive": 0
            },
            "app_id": null
        }
    ],
    "data_count" : "1",
    "mode" : "test",
}

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¶

{
     "id":"sub_09a1944830b7e37e2005",
     "offer":"<Object>",
     "livemode":false,
     "amount":299,
     "temp_amount":null,
     "currency":"USD",
     "name":"Testing",
     "interval":"1 DAY",
     "trial_start":1400555454,
     "trial_end":null,
     "period_of_validity":null,
     "end_of_period":null,
     "next_capture_at":1400642826,
     "created_at":1400555454,
     "updated_at":1400556426,
     "canceled_at":null,
     "payment":"<Object>",
     "app_id":null,
     "is_canceled":false,
     "is_deleted":false,
     "status":"failed",
     "client":"<Object>"
 }

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

Attributes¶

id: string Unique identifier of this subscription.
livemode: boolean Whether this subscription was issued while being in live mode or not.
offer: offer object
amount: integer the amount of the subscription in cents
temp_amount: integer or null a one-time amount in cents, will charge once only
curreny: string ISO 4217 formatted currency code
interval: string Defining how often the client should be charged. Format: number DAY|WEEK|MONTH|YEAR [, WEEKDAY] Example: 2 DAYS, MONDAY
name: string or null name of the subscription
trial_start: integer or null Unix-Timestamp for the trial period start
trial_end: integer or null Unix-Timestamp for the trial period end.
period_of_validity: string or null limit the validity of the subscription, format: integer MONTH|YEAR|WEEK|DAY
end_of_period: Unix-Timestamp or null expiring date of the subscription
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.
is_canceled: boolean subscription is marked as canceled or not
is_deleted: boolean subscription is marked as deleted or not
status: string shows, if subscription is “active”, “inactive”, “expired” or “failed”

This function connects the offer with a client.

Create new `Subscription` ...¶

Without an offer

Request

curl <PAYMILL_URL>subscriptions \
  -u <DEIN_PRIVATE_KEY>: \
  -d "client=client_81c8ab98a8ac5d69f749" \
  -d "payment=pay_5e078197cde8a39e4908f8aa" \
  -d "amount=3000" \
  -d "currency=EUR" \
  -d "interval=1 week,monday" \
  -d "name=Example Subscription" \
  -d "period_of_validity=2 YEAR" \
  -d "start_at=1400575533"

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

Response

{
    "data":{
            "id":"sub_dea86e5c65b2087202e3",
            "offer":{<Object>},
            "livemode":false,
            "amount":3000,
            "temp_amount":null,
            "currency":"EUR",
            "name":"Example Subscription",
            "interval":"1 WEEK,MONDAY",
            "trial_start":1399908040,
            "trial_end":1400575532,
            "period_of_validity":"2 YEAR",
            "end_of_period":1461429607,
            "next_capture_at":1400575532,
            "created_at":1398271207,
            "updated_at":1398271207,
            "canceled_at":null,
            "payment":{<Object>},
            "app_id":null,
            "is_canceled":false,
            "is_deleted":false,
            "status":"active",
            "client":{<Object>}
    },
    "mode":"test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

With an offer

Request

curl <PAYMILL_URL>subscriptions \
  -u <DEIN_PRIVATE_KEY>: \
  -d "client=client_64b025ee5955abd5af66" \
  -d "offer=offer_40237e20a7d5a231d99b" \
  -d "payment=pay_95ba26ba2c613ebb0ca8" \
  -d "period_of_validity=2 YEAR" \
  -d "start_at=1400575533"

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

Response

{
    "data":{
            "id":"sub_dea86e5c65b2087202e3",
            "offer":{<Object>},
            "livemode":false,
            "amount":3333,
            "temp_amount":null,
            "currency":"USD",
            "name":"Offer Name",
            "interval":"2 WEEK",
            "trial_start":1399908040,
            "trial_end":1400575532,
            "period_of_validity":"2 YEAR",
            "end_of_period":1461429607,
            "next_capture_at":1400575532,
            "created_at":1398271207,
            "updated_at":1398271207,
            "canceled_at":null,
            "payment":{<Object>},
            "app_id":null,
            "is_canceled":false,
            "is_deleted":false,
            "status":"active",
            "client":{<Object>}
    },
    "mode":"test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

With offer and different values

Request

curl <PAYMILL_URL>subscriptions \
  -u <DEIN_PRIVATE_KEY>: \
  -d "client=client_81c8ab98a8ac5d69f749" \
  -d "payment=pay_5e078197cde8a39e4908f8aa" \
  -d "offer=offer_b33253c73ae0dae84ff4" \
  -d "amount=3000" \
  -d "currency=EUR" \
  -d "interval=1 week,monday" \
  -d "name=Example Subscription" \
  -d "period_of_validity=2 YEAR" \
  -d "start_at=1400575533"

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

Response

{
    "data":{
            "id":"sub_dea86e5c65b2087202e3",
            "offer":{<Object>},
            "livemode":false,
            "amount":3000,
            "temp_amount":null,
            "currency":"EUR",
            "name":"Example Subscription",
            "interval":"1 WEEK,MONDAY",
            "trial_start":1399908040,
            "trial_end":1400575532,
            "period_of_validity":"2 YEAR",
            "end_of_period":1461429607,
            "next_capture_at":1400575532,
            "created_at":1398271207,
            "updated_at":1398271207,
            "canceled_at":null,
            "payment":{<Object>},
            "app_id":null,
            "is_canceled":false,
            "is_deleted":false,
            "status":"active",
            "client":{<Object>}
    },
    "mode":"test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

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 (if no offer is given, amount, currency and interval are required)
payment: string Unique payment identifier
client: string Unique client identifier. If not provided the client from the payment is being used.
amount: integer (>0) the amount of the subscription in cents (is required if no offer id is given)
currency: string ISO 4217 formatted currency code (is required if no offer id is given)
interval: string Defining how often the client should be charged. Format: number DAY|WEEK|MONTH|YEAR [, WEEKDAY] Example: 2 DAYS, MONDAY ( is required if no offer id is given)
name: string or null name of the subscription (optional)
period_of_validity: string or null limit the validity of the subscription, format: integer MONTH|YEAR|WEEK|DAY (optional)
start_at: integer or null Unix-Timestamp for the subscription start date, if trial_end > start_at, the trial_end will be set to start_at (optional)

`Subscription` Details¶

curl <PAYMILL_URL>subscriptions/sub_dc180b755d10da324864 \
  -u <DEIN_PRIVATE_KEY>:

$subscription = new Paymill\Models\Request\Subscription();
$subscription->setId('sub_dc180b755d10da324864');

$response = $request->getOne($subscription);

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
Subscription subscription = subscriptionService.get("sub_dc180b755d10da324864");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.subscriptions.details('sub_dc180b755d10da324864',
    function(err, subscription) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("subscription id " + subscription.data.id);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
subscription = p.getsubdetails(sid='sub_dc180b755d10da324864')

Paymill::Subscription.find "sub_dc180b755d10da324864"

SubscriptionService subscriptionService = paymillContext.SubscriptionService;
Subscription subscription = subscriptionService.GetAsync("sub_dc180b755d10da324864").Result;

pm.subscriptions.detail("sub_dc180b755d10da324864").then(function(subscription) {
	console.log("subscription:" + subscription.id);
}, function(error) {
	console.log("couldnt get subscription:" + error);
});

Response

{
    "data" :{
            "id":"sub_dea86e5c65b2087202e3",
            "offer":{<Object>},
            "livemode":false,
            "amount":3000,
            "temp_amount":null,
            "currency":"EUR",
            "name":"Example Subscription",
            "interval":"1 WEEK,MONDAY",
            "trial_start":1399908040,
            "trial_end":1400575532,
            "period_of_validity":"2 YEAR",
            "end_of_period":1461429607,
            "next_capture_at":1400575532,
            "created_at":1398271207,
            "updated_at":1398271207,
            "canceled_at":null,
            "payment":{<Object>},
            "app_id":null,
            "is_canceled":false,
            "is_deleted":false,
            "status":"active",
            "client":{<Object>}
    },
    "mode" : "test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

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

Attributes¶

id: string Unique identifier for the subscription

Update `Subscription` ...¶

General

Request

curl <PAYMILL_URL>subscriptions/sub_dea86e5c65b2087202e3 \
  -u <DEIN_PRIVATE_KEY>: \
  -d "offer=offer_40237e20a7d5a231d99b" \
  -d "payment=pay_95ba26ba2c613ebb0ca8" \
  -d "currency=USD" \
  -d "interval=1 month,friday" \
  -d "name=Changed Subscription" \
  -d "period_of_validity=14 MONTH" \
  -d "trial_end=false" \
  -X PUT

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

Response

{
    "data" :{
            "id":"sub_dea86e5c65b2087202e3",
            "offer":{<Object>},
            "livemode":false,
            "amount":3000,
            "temp_amount":null,
            "currency":"USD",
            "name":"Changed Subscription",
            "interval":"1 MONTH,FRIDAY",
            "trial_start":1399908040,
            "trial_end":null,
            "period_of_validity":"12 MONTH",
            "end_of_period":1435063506,
            "next_capture_at":1400575532,
            "created_at":1398271207,
            "updated_at":1398343548,
            "canceled_at":null,
            "payment":{<Object>},
            "app_id":null,
            "is_canceled":false,
            "is_deleted":false,
            "status":"active",
            "client":{<Object>}
    },
    "mode" : "test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

Amount

Request

curl <PAYMILL_URL>subscriptions/sub_dea86e5c65b2087202e3 \
  -u <DEIN_PRIVATE_KEY>: \
  -d "amount=1234" \
  -d "amount_change_type=0" \
  -X PUT

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

Response

{
    "data" : {
        "id":"sub_dea86e5c65b2087202e3",
        "offer" : "<Object>",
        "livemode":false,
        "amount":3000,
        "temp_amount":"1234",
        "currency":"EUR",
        "name":"Example Subscription",
        "interval":"1 WEEK,MONDAY",
        "trial_start":1398271207,
        "trial_end":1399196896,
        "period_of_validity":"2 YEAR",
        "end_of_period":1461429607,
        "next_capture_at":1399308007,
        "created_at":1398271207,
        "updated_at":1398271302,
        "canceled_at":null,
        "payment": "<Object>",
        "app_id":null,
        "is_canceled":false,
        "is_deleted":false,
        "status":"active",
        "client" : "<Object>"
    },
    "mode" : "test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

Offer

Request

curl <PAYMILL_URL>subscriptions/sub_dea86e5c65b2087202e3 \
  -u <DEIN_PRIVATE_KEY>: \
  -d "offer=offer_d7e9813a25e89c5b78bd" \
  -d "offer_change_type=2" \
  -X PUT

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

Response

{
    "data" : {
        "id":"sub_dea86e5c65b2087202e3",
        "offer" : "<Object>",
        "livemode":false,
        "amount":3000,
        "temp_amount":null,
        "currency":"EUR",
        "name":"Example Subscription",
        "interval":"1 WEEK,MONDAY",
        "trial_start":1398271207,
        "trial_end":1399196896,
        "period_of_validity":"2 YEAR",
        "end_of_period":1461429607,
        "next_capture_at":1399308007,
        "created_at":1398271207,
        "updated_at":1398271302,
        "canceled_at":null,
        "payment": "<Object>",
        "app_id":null,
        "is_canceled":false,
        "is_deleted":false,
        "status":"active",
        "client" : "<Object>"
    },
    "mode" : "test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

Pause

Request

curl <PAYMILL_URL>subscriptions/sub_dea86e5c65b2087202e3 \
  -u <DEIN_PRIVATE_KEY>: \
  -d "pause=true" \
  -X PUT

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

Response

{
    "data" : {
        "id":"sub_dea86e5c65b2087202e3",
        "offer" : "<Object>",
        "livemode":false,
        "amount":3000,
        "temp_amount":null,
        "currency":"EUR",
        "name":"Example Subscription",
        "interval":"1 WEEK,MONDAY",
        "trial_start":1398271207,
        "trial_end":1399196896,
        "period_of_validity":"2 YEAR",
        "end_of_period":1461429607,
        "next_capture_at":1399308007,
        "created_at":1398271207,
        "updated_at":1398271302,
        "canceled_at":null,
        "payment": "<Object>",
        "app_id":null,
        "is_canceled":false,
        "is_deleted":false,
        "status":"inactive",
        "client" : "<Object>"
    },
    "mode" : "test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

This function updates the subscription of a client. You can change e.g. the trial_end attribute to stop the trial period. Or you can assign the subscription to another offer (offer=<new_offer_id>), change the amount or pause it. NOTE: changing the amount and offer within one request is not possible (throw an exception).

Attributes¶

id: string Unique identifier for the subscription
payment: string Unique identifier describing a payment of the client
offer: string Unique identifier describing the offer which is subscribed to the client (optional)
offer_change_type: int or null permitted values: 0,1,2; linked and required with ‘offer’, default: 0 (optional)
amount: integer (>0) the amount of the subscription in cents (optional)
amount_change_type: int permitted values: 0,1; linked and required with ‘amount’ (optional)
pause: boolean deactivate a subscription or reactivate it, false: reactivate, true: deactivate (optional)
currency: string ISO 4217 formatted currency code (optional)
interval: string Defining how often the client should be charged. Format: number DAY|WEEK|MONTH|YEAR [, WEEKDAY] (optional)
name: string name of the subscription (optional)
period_of_validity: string limit the validity of the subscription, format: integer MONTH|YEAR|WEEK|DAY, set to “remove” to unlimit the validity period (optional)
trial_end: boolean set to false to stop the trial period immediatly (optional)

Cancel or Delete `Subscription`¶

Cancel

Request

curl <PAYMILL_URL>subscriptions/sub_d68bcdc8656a7932eb44 \
  -u <DEIN_PRIVATE_KEY>: \
  -d "remove=false" \
  -X DELETE

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

/* … not yet implemented for subscription v2.1 for this wrapper.
Please use the old version of subscription v2.0 and have a look in the V2.0 PDF … */

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

# … not yet implemented for subscription v2.1 for this wrapper.
# Please use the old version of subscription v2.0 and have a look in the V2.0 PDF …

Response

{
    "data" : {
        "id":"sub_dea86e5c65b2087202e3",
        "offer" : "<Object>",
        "livemode":false,
        "amount":3000,
        "temp_amount":null,
        "currency":"EUR",
        "name":"Example Subscription",
        "interval":"1 WEEK,MONDAY",
        "trial_start":1398271207,
        "trial_end":1399196896,
        "period_of_validity":"2 YEAR",
        "end_of_period":1461429607,
        "next_capture_at":1399308007,
        "created_at":1398271207,
        "updated_at":1398271302,
        "canceled_at":1401194748,
        "payment": "<Object>",
        "app_id":null,
        "is_canceled":true,
        "is_deleted":false,
        "status":"active",
        "client" : "<Object>"
    },
    "mode" : "test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

Delete

Request

curl <PAYMILL_URL>subscriptions/sub_d68bcdc8656a7932eb44 \
  -u <DEIN_PRIVATE_KEY>: \
  -d "remove=true" \
  -X DELETE

$subscription = new Paymill\Models\Request\Subscription();
$subscription->setId('sub_dc180b755d10da324864');

$response = $request->delete($subscription);

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
subscriptionService.delete("sub_dc180b755d10da324864");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.subscriptions.remove('sub_dc180b755d10da324864',
    function(err, subscription) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("deleted the subscription");
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
response = p.cancelsubnow(sid='sub_012db05186ccfe22d86c')

Paymill::Subscription.delete "sub_dc180b755d10da324864"

SubscriptionService subscriptionService = paymillContext.SubscriptionService;
subscriptionService.DeleteAsync("sub_dc180b755d10da324864").Result;

pm.subscriptions.detail("sub_dc180b755d10da324864").then(function(subscription) {
	console.log("deleted subscription:" + subscription.id);
}, function(error) {
	console.log("couldnt get subscription:" + error);
});

Response

{
    "data" : {
        "id":"sub_dea86e5c65b2087202e3",
        "offer" : "<Object>",
        "livemode":false,
        "amount":3000,
        "temp_amount":null,
        "currency":"EUR",
        "name":"Example Subscription",
        "interval":"1 WEEK,MONDAY",
        "trial_start":1398271207,
        "trial_end":1399196896,
        "period_of_validity":"2 YEAR",
        "end_of_period":1461429607,
        "next_capture_at":1399308007,
        "created_at":1398271207,
        "updated_at":1398271302,
        "canceled_at":1401194748,
        "payment": "<Object>",
        "app_id":null,
        "is_canceled":true,
        "is_deleted":true,
        "status":"active",
        "client" : "<Object>"
    },
    "mode" : "test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

This function cancels or remove an existing subscription. The subscription will be directly terminated or deleted and no pending transactions will be charged. Deleted subscriptions will not be displayed.

Attributes¶

id: string Unique identifier for the subscription
remove: boolean cancel (false) or delete (true) a subscription

List `Subscriptions`¶

curl <PAYMILL_URL>subscriptions \
  -u <DEIN_PRIVATE_KEY>:

$subscription = new Paymill\Models\Request\Subscription();

$response = $request->getAll($subscription);

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
PaymillList<Subscription> subscriptions = subscriptionService.list();

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.subscriptions.list({},
    function(err, subscription) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("subscription data " + subscription.data);
    }
);

private_key = '<DEIN_PRIVATE_KEY>'
p = pymill.Pymill(private_key)
subscriptions = p.getsubs()

Paymill::Subscription.all

SubscriptionService subscriptionService = paymillContext.SubscriptionService;
PaymillList<Subscription> subscriptions = subscriptionService.ListAsync().Result;

pm.subscriptions.list().then(function(pmlist) {
	console.log(pmlist.items.length + " offers from total of " + pmlist.count);
}, function(error) {
	console.log("couldnt list subscriptions:" + error);
});

Response

{
    "data" : [
        {
            "id":"sub_dc180b755d10da324864",
            "offer" : "<Object>",
            "livemode" : false,
            "cancel_at_period_end" : false,
            "trial_start": null,
            "trial_end": null,
            "next_capture_at": 1369563095,
            "created_at" : 1341935490,
            "updated_at" : 1349948303,
            "canceled_at" : 1349948303,
            "payment": "<Object>",
            "client" : "<Object>",
            "app_id" : null
        }
    ],
    "data_count" : "1",
    "mode" : "test"
}

Sub objects

subscription.offer returns an offer object
subscription.payment returns a payment object for credit card or a payment object for direct debit
subscription.client returns a client object

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¶

we expect a http status code of 200 in the response of our webhook call.
every content in the body will be discarded, so you might just leave that blank.
if we receive another code or a timeout, we will retry to call the same webhook every hour up to five times. emails will be sent only once.
if the webhook call to one webhook fails 5 times, we automatically deactivate the webhook. You can still see them in your settings.
the webhook will be called asynchronously within a few minutes after the actual event has happened.

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`¶

chargeback.executed: returns a transaction-object with state set to chargeback
transaction.created: returns a transaction-object
transaction.succeeded: returns a transaction-object
transaction.failed: returns a transaction-object
client.updated: returns a client-object if a client was updated
subscription.created: returns a subscription-object
subscription.updated: returns a subscription-object
subscription.deleted: returns a subscription-object
subscription.succeeded: returns a transaction-object and a subscription-object
subscription.failed: returns a transaction-object and a subscription-object
subscription.expiring: returns a subscription-object
subscription.deactivated: returns a subscription-object
subscription.activated: returns a subscription-object
subscription.canceled: returns a subscription-object
refund.created: returns a refund-object
refund.succeeded: returns a refunds-object
refund.failed: returns a refunds-object
payout.transferred: returns an invoice-object with the payout sum for the invoice period
invoice.available: returns an invoice-object with the fees sum for the invoice period
app.merchant.activated: returns a merchant-object if a connected merchant was activated
app.merchant.deactivated: returns a merchant-object if a connected merchant was deactivated
app.merchant.rejected: returns a merchant-object if a connected merchant was rejected
app.merchant.live_requests_allowed: returns a merchant-object if a connected merchant allows live requests
app.merchant.live_requests_not_allowed: returns a merchant-object if a connected merchant denys live requests
app.merchant.app.disabled: returns a merchant object if a connected merchant disabled your app
payment.expired: returns a payment-object if a creditcard is going to expire next month

Example event

{
    "event": {
        "event_type": "subscription.succeeded",
        "event_resource": {
           "subscription": "<Object>",
           "transaction": "<Object>"
        },
        "created_at": "1358027174",
        "app_id": null
    }
 }

$body = @file_get_contents('php://input');
$event_json = json_decode($body, true);

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¶

{
     "id":"hook_40237e20a7d5a231d99b",
     "url":"<your-webhook-url>",
     "livemode":false,
     "event_types":[
         "transaction.succeeded",
         "transaction.failed"
     ],
     "created_at":1358982000,
     "updated_at":1358982000,
     "active":true,
     "app_id":null
}

Example e-mail webhook

{
     "id":"hook_40237e20a7d5a231d99b",
     "email":"<your-webhook-email>",
     "livemode":false,
     "event_types":[
         "transaction.succeeded",
         "transaction.failed"
     ],
     "created_at":1358982000,
     "updated_at":1358982000,
     "active":true,
     "app_id":null
}

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`¶

curl <PAYMILL_URL>webhooks \
-u <DEIN_PRIVATE_KEY>: \
-d "url=<your-webhook-url>" \
-d "event_types[]=subscription.succeeded" \
-d "event_types[]=subscription.failed"

$webhook = new Paymill\Models\Request\Webhook();
$webhook->setUrl('<your-webhook-url>')
        ->setEventTypes(array(
            'transaction.succeeded',
            'subscription.created'
        ));

$response = $request->create($webhook);

WebhookService webhookService = paymillContext.getWebhookService();
EventType[] eventTypes = new EventType[] {
    EventType.CLIENT_UPDATED,
    EventType.TRANSACTION_SUCCEEDED
};
Webhook webhook = webhookService.createUrlWebhook(
    "<your-webhook-url>",
    eventTypes
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.webhooks.create(
    {
        url: '<your-webhook-url>',
        event_types: ['subscription.succeeded”', 'subscription.failed']
	},
    function(err, webhook) {
        if (err) {
            console.log("Couldn't create the webhook record");
            return;
        }
        console.log(webhook.data);
    }
);

Paymill::Webhook.create url: "<your-webhook-url>",
    event_types: ["transaction.succeeded", "transaction.failed"]

WebhookService webhookService = paymillContext.WebhookService;
EventType[] eventTypes = new EventType[] {
    EventType.CLIENT_UPDATED,
    EventType.TRANSACTION_SUCCEEDED
}.Result;
Webhook webhook = webhookService.CreateUrlWebhookAsync(
    "<your-webhook-url>",
    eventTypes
).Result;

pm.webhooks.createUrl("<your-webhook-url>",[pm.Webhook.EventType.TRANSACTION_SUCCEDED]).then(function(webhook) {
	console.log("created webhook:" + webhook.id);
}, function(error) {
	console.log("couldnt get webhook:" + error);
});

Response

{
    "data" : {
            "id":"hook_40237e20a7d5a231d99b",
            "url":"<your-webhook-url>",
            "livemode":false,
            "event_types":[
                "transaction.succeeded",
                "transaction.failed"
            ],
            "created_at":1358982000,
            "updated_at":1358982000,
            "active" : true,
            "app_id" : null
        },
        "mode" : "test"
}

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`¶

curl <PAYMILL_URL>webhooks \
-u <DEIN_PRIVATE_KEY>: \
-d "email=<your-webhook-email>" \
-d "event_types[]=subscription.succeeded" \
-d "event_types[]=subscription.failed"

$webhook = new Paymill\Models\Request\Webhook();
$webhook->setEmail('<your-webhook-email>')
        ->setEventTypes(array(
            'transaction.succeeded',
            'subscription.created'
        ));

$response = $request->create($webhook);

WebhookService webhookService = paymillContext.getWebhookService();
EventType[] eventTypes = new EventType[] {
    EventType.CLIENT_UPDATED,
    EventType.TRANSACTION_SUCCEEDED
};
Webhook webhook = webhookService.createEmailWebhook(
    "<your-webhook-email>",
    eventTypes
);

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.webhooks.create(
    {
        email: '<your-webhook-email>',
        event_types: ['subscription.succeeded”', 'subscription.failed']
	},
    function(err, webhook) {
        if (err) {
            console.log("Couldn't create the webhook record");
            return;
        }
        console.log(webhook.data);
    }
);

Paymill::Webhook.create email: "<your-webhook-email>",
    event_types: ["transaction.succeeded", "transaction.failed"]

WebhookService webhookService = paymillContext.WebhookService;
EventType[] eventTypes = new EventType[] {
    EventType.CLIENT_UPDATED,
    EventType.TRANSACTION_SUCCEEDED
};
Webhook webhook = webhookService.CreateEmailWebhookAsync(
    "<your-webhook-email>",
    eventTypes
).Result;

pm.webhooks.createEmail("<your-webhook-email>",[pm.Webhook.EventType.TRANSACTION_SUCCEDED]).then(function(webhook) {
	console.log("created webhook:" + webhook.id);
}, function(error) {
	console.log("couldnt get webhook:" + error);
});

Response

{
    "data" : {
            "id" : "hook_40237e20a7d5a231d99b",
            "email" : "<your-webhook-email>",
            "livemode" : false,
            "event_types" : [
                "transaction.succeeded",
                "transaction.failed"
            ],
            "created_at" : 1358982000,
            "updated_at" : 1358982000,
            "active" : true,
            "app_id" : null
        },
        "mode" : "test"
}

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¶

curl <PAYMILL_URL>webhooks/hook_40237e20a7d5a231d99b \
-u <DEIN_PRIVATE_KEY>:

$webhook = new Paymill\Models\Request\Webhook();
$webhook->setId('hook_40237e20a7d5a231d99b');

$response = $request->getOne($webhook);

WebhookService webhookService = paymillContext.getWebhookService();
Webhook webhook = webhookService.get("hook_40237e20a7d5a231d99b");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.webhooks.details('hook_40237e20a7d5a231d99b',
    function(err, webhook) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("webhook id " + webhook.data.id);
    }
);

Paymill::Webhook.find "hook_40237e20a7d5a231d99b"

WebhookService webhookService = paymillContext.WebhookService;
Webhook webhook = webhookService.GetAsync("hook_40237e20a7d5a231d99b").Result;

pm.webhooks.detail("hook_40237e20a7d5a231d99b").then(function(webhook) {
	console.log("webhook:" + webhook.id);
}, function(error) {
	console.log("couldnt get webhook:" + error);
});

Response

 {
    "data" : {
        "id":"hook_40237e20a7d5a231d99b",
        "url":"<your-webhook-url>",
        "livemode":false,
        "event_types":[
            "transaction.succeeded",
            "transaction.failed"
        ],
        "created_at":1358982000,
        "updated_at":1358982000,
        "active" : true,
        "app_id" : null
    },
    "mode" : "test"
}

Response of an e-mail webhook

 {
    "data" : {
        "id":"hook_40237e20a7d5a231d99b",
        "email":"<your-webhook-email>",
        "livemode":false,
        "event_types":[
            "transaction.succeeded",
            "transaction.failed"
        ],
        "created_at":1358982000,
        "updated_at":1358982000,
        "active" : true,
        "app_id" : null
    },
    "mode" : "test"
}

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

Update `Webhook`¶

curl <PAYMILL_URL>webhooks/hook_40237e20a7d5a231d99b \
   -u <DEIN_PRIVATE_KEY>: \
   -d "url=<new-webhook-url>" \
   -X PUT

$webhook = new Paymill\Models\Request\Webhook();
$webhook->setId('hook_40237e20a7d5a231d99b')
        ->setUrl('<your-webhook-url>')
        ->setEventTypes(array(
            'transaction.failed',
            'subscription.failed'
        ));

$response = $request->update($webhook);

WebhookService webhookService = paymillContext.getWebhookService();
Webhook webhook = webhookService.get("hook_40237e20a7d5a231d99b");
webhook.setUrl("http://www.example.org");
webhookService.update( webhook );

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.webhooks.update('hook_40237e20a7d5a231d99b', {
        url: '<your-webhook-url>'
  }, function(err, webhook) {
        if (err) {
            console.log("Couldn't update the webhook record");
            return;
        }
        console.log("webhook id " + webhook.data.id);
    }
);

Paymill::Webhook.update_attributes "hook_40237e20a7d5a231d99b",
    url: "<new-webhook-url>"
# or
webhook = Paymill::Webhook.create url: "<your-webhook-url>",
    event_types: ["transaction.succeeded", "transaction.failed"]
webhook.update_attributes url: "<new-webhook-url>"

WebhookService webhookService = paymillContext.WebhookService;
Webhook webhook = webhookService.GetAsync("hook_40237e20a7d5a231d99b").Result;
webhook.Email = "[email protected]";
webhookService.UpdateAsync( webhook ).Wait();

pm.webhooks.detail("hook_40237e20a7d5a231d99b").then(function(webhook) {
	webhook.email = "<your-udpated-webhook-email>";
	return pm.webhooks.update(webhook);
}).then(function(updatedWebhook) {
	console.log("updated webhook:" + updatedWebhook.description);
}, function(error) {
	console.log("couldnt update webhook:" + error);
});

Response

{
    "data" : {
        "id":"hook_40237e20a7d5a231d99b",
        "url":"<your-webhook-url>",
        "livemode":false,
        "event_types":[
            "transaction.succeeded",
            "transaction.failed"
        ],
        "created_at":1358982000,
        "updated_at":1358982000,
        "active" : true,
        "app_id" : null
    },
    "mode" : "test"
}

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`¶

curl <PAYMILL_URL>webhooks/hook_40237e20a7d5a231d99b \
-u <DEIN_PRIVATE_KEY>: \
-X DELETE

$webhook = new Paymill\Models\Request\Webhook();
$webhook->setId('hook_40237e20a7d5a231d99b');

$response = $request->delete($webhook);

WebhookService webhookService = paymillContext.getWebhookService();
Webhook webhook = webhookService.delete("hook_40237e20a7d5a231d99b");

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.webhooks.remove('hook_88a388d9dd48f86c3136',
    function(err, webhook) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("deleted the webhook");
    }
);

Paymill::Webhook.delete "hook_40237e20a7d5a231d99b"

WebhookService webhookService = paymillContext.WebhookService;
Webhook webhook = webhookService.DeleteAsync("hook_40237e20a7d5a231d99b").Result;

pm.webhooks.remove("hook_40237e20a7d5a231d99b").then(function(webhook) {
	console.log("deleted webhook:" + webhook.id);
}, function(error) {
	console.log("couldnt get webhook:" + error);
});

Response

{
    "data":[

    ],
    "mode" : "test"
}

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

List `Webhooks`¶

curl <PAYMILL_URL>webhooks/ \
  -u <DEIN_PRIVATE_KEY>:

$webhook = new Paymill\Models\Request\Webhook();
$webhook->setFilter(array(
    'count' => 2,
    'offset' => 0
));

$response = $request->getAll($webhook);

WebhookService webhookService = paymillContext.getWebhookService();
PaymillList<Webhook> webhooks = webhookService.list();

var api_key = '<DEIN_PRIVATE_KEY>';  // secret paymill API key
var paymill = require('paymill-node')(api_key);

paymill.webhooks.list({},
    function(err, webhook) {
        if (err) {
            console.log("Error :(");
            return;
        }
        console.log("webhook data " + webhook.data);
    }
);

Paymill::Webhook.all

WebhookService webhookService = paymillContext.WebhookService;
PaymillList<Webhook> webhooks = webhookService.ListAsync();

pm.webhooks.list().then(function(pmlist) {
	console.log(pmlist.items.length + " webhooks from total of " + pmlist.count);
}, function(error) {
	console.log("couldnt list webhooks:" + error);
});

Response

{
    "data" : [
        {
            "id":"hook_40237e20a7d5a231d99b",
            "url":"<your-webhook-url>",
            "livemode":false,
            "event_types":[
                "transaction.succeeded",
                "transaction.failed"
            ],
            "created_at":1358982000,
            "updated_at":1358982000,
            "active" : true,
            "app_id" : null
        },
        {
            "id":"hook_40237e20a7d5skt6d99b",
            "email":"<your-webhook-email>",
            "livemode":false,
            "event_types":[
                "subscription.succeeded",
                "subscription.failed"
            ],
            "created_at":1358911000,
            "updated_at":1358913000,
            "active" : true,
            "app_id" : null
        }
    ],
    "data_count" : "2",
    "mode" : "test"
}

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 or null 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)

PAYMILL API/V2.1 DOCUMENTATION¶

Authentication¶

Response Codes¶

Errors¶

Listviews¶

Sort Entries¶

Filter Entries¶

Payments¶

Payment Object for credit card payments¶

Attributes¶

Payment Object for direct debit payments¶

Attributes¶

Create new Credit Card Payment with ...¶

Attributes¶

Create new Debit Payment with ...¶

Attributes¶

Payment Details¶

Attributes¶

List Payments¶

Remove Payment¶

Attributes¶

Preauthorizations¶

Preauthorization Object¶

Attributes¶

Create new Preauthorization with ...¶

Attributes¶

Preauthorization Details¶

Attributes¶

Remove Preauthorizations¶

Attributes¶

List Preauthorizations¶

Transactions¶

Transaction Object¶

Attributes¶

Create new Transaction with ...¶

Attributes¶

Transaction Details¶

Attributes¶

Update Transaction¶

Attributes¶

List Transactions¶

Refunds¶

Refund Object¶

Attributes¶

Refund Transaction¶

Attributes¶

Refund Details¶

List Refunds¶

Clients¶

Client Object¶

Attributes¶

Create new Client¶

Attributes¶

Client Details¶

Attributes¶

Update Client¶

Attributes¶

Remove Client¶

Attributes¶

List Clients¶

Export Client List¶

Offers¶

Offer Object¶

Attributes¶

Create new Offer¶

Attributes¶

Offer Details¶

Attributes¶

Update Offer¶

Attributes¶

Remove Offer¶

Attributes¶

List Offers¶

Subscriptions¶

Subscription Object¶

Attributes¶

Create new Subscription ...¶

Attributes¶

Subscription Details¶

Attributes¶

`Payment` Object for credit card payments¶

`Payment` Object for direct debit payments¶

Create new `Credit Card Payment` with ...¶

Create new `Debit Payment` with ...¶

`Payment` Details¶

List `Payments`¶

Remove `Payment`¶

`Preauthorization` Object¶

Create new `Preauthorization` with ...¶

`Preauthorization` Details¶

Remove `Preauthorizations`¶

List `Preauthorizations`¶

`Transaction` Object¶

Create new `Transaction` with ...¶

`Transaction` Details¶

Update `Transaction`¶

List `Transactions`¶

`Refund` Object¶

`Refund` Transaction¶

`Refund` Details¶

List `Refunds`¶

`Client` Object¶

Create new `Client`¶

`Client` Details¶

Update `Client`¶

Remove `Client`¶

List `Clients`¶

Export `Client` List¶

`Offer` Object¶

Create new `Offer`¶

`Offer` Details¶

Update `Offer`¶

Remove `Offer`¶

List `Offers`¶

`Subscription` Object¶

Create new `Subscription` ...¶

`Subscription` Details¶

Update `Subscription` ...¶

Cancel or Delete `Subscription`¶

List `Subscriptions`¶

`Events`¶

`Webhook` Object¶

Create new `URL Webhook`¶

Create new `E-Mail Webhook`¶

`Webhook` Details¶

Update `Webhook`¶

Remove `Webhook`¶

List `Webhooks`¶

`Fee` Object¶

`Invoice` Object¶

`Merchant` Object¶

`Payment method` Object¶