Curl
API REFERENCE

Introduction

API Endpoint

https://api.paymill.com/v2.1/

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.

Authentication

% curl https://api.paymill.com/v2.1/clients \
    -u <YOUR_PRIVATE_KEY>
Paymill.api_key = ""

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

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

paymill_context = paymill.PaymillContext('< YOUR_PRIVATE_API_KEY >');

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

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

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

Note:

  • Please keep your private keys secure and don't pass them to anybody. These private keys have extreme secure information for handling the transactions of your shop.

  • All your requests must be made via https. Requests which will be made in another way will fail. This is for security reasons of the submitted data.

Response Codes

Some response objects like transactions or refunds include a response code that provides more detailed information about the outcome of a request.

These codes are 5-digit numbers whereas the first digit indicates whether the request is in progress (1xxxx), successful (2xxxx), pending (3xxxx) or failed because of client-side errors (4xxxx) or server-side errors (5xxxx).

Possible response codes

10001: Undefined response
10002: Waiting for something
11000: Retry request at a later time

20000: Operation successful
20100: Funds held by acquirer
20101: Funds held by acquirer because merchant is new
20200: Transaction reversed
20201: Reversed due to chargeback
20202: Reversed due to money-back guarantee
20203: Reversed due to complaint by buyer
20204: Payment has been refunded
20300: Reversal has been canceled

30000: Transaction still in progress
30100: Transaction has been accepted
31000: Transaction pending
31100: Pending due to address
31101: Pending due to uncleared eCheck
31102: Pending due to risk review
31103: Pending due regulatory review
31104: Pending due to unregistered/unconfirmed receiver
31200: Pending due to unverified account
31201: Pending due to non-captured funds
31202: Pending due to international account (accept manually)
31203: Pending due to currency conflict (accept manually)
31204: Pending due to fraud filters (accept manually)

40000: Problem with transaction data
40001: Problem with payment data
40002: Invalid checksum
40100: Problem with credit card data
40101: Problem with CVV
40102: Card expired or not yet valid
40103: Card limit exceeded
40104: Card is not valid
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 3-D 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
40410: Problem with shopping cart data
40420: Problem with address data
40500: Permission error with acquirer API
40510: Rate limit reached for acquirer API

50000: Problem with back end
50001: Country blacklisted
50002: IP address blacklisted
50004: Live mode not allowed
50005: Insufficient permissions (API key)
50100: Technical error with credit card
50101: Error limit exceeded
50102: Card declined
50103: Manipulation or stolen card
50104: Card restricted
50105: Invalid configuration data
50200: Technical error with bank account
50201: Account blacklisted
50300: Technical error with 3-D Secure
50400: Declined because of risk issues
50420: Rejected due to acquirer fraud settings
50430: Rejected due to acquirer risk settings
50440: Failed due to PayPal account restrictions
50500: General timeout
50501: Timeout on side of the acquirer
50502: Risk management transaction timeout
50600: Duplicate transaction
50700: Cancelled by user
50710: Failed due to funding source
50711: Payment method not usable, use other payment method
50720: Rejected by acquirer
50730: Transaction denied by merchant
50800: Preauthorisation failed
50810: Authorisation has been voided
50820: Authorisation period expired

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

HTTP Status Codes we use

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
Code Meaning Description
200 OK Great, go ahead.
401 Unauthorized Jim, You have to provide your private API Key.
403 Transaction Error Transaction could not be completed, please check your payment data.
404 Not Found There is no entity with this identifier, did you use the right one?
412 Precondition Failed I guess you're missing at least one required parameter?
5xx Server Error Doh, 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

Example:

?order=amount | ?order=amount_asc | ?order=amount_desc

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.

Filter Entries

Example:

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

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.

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

Example

{
    "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,
    "is_recurring" : true,
    "is_usable_for_preauthorization" : true
}

Attributes

id: string
Unique identifier for this credit card payment

type: enum (creditcard, debit, paypal)

client: client object / null

card_type: string
Card type. eg. visa, mastercard ...

country: string / 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 / null
App (ID) that created this payment or null if created by yourself

is_recurring: boolean
The payment is recurring (can be used more than once)

is_usable_for: boolean
The payment is usable for preauthorization

Payment object for direct debit payments

Example

{
    "id"           : "pay_917018675b21ca03c4fb",
    "type"         : "debit",
    "client"       : null,
    "code"         : "12345678",
    "holder"       : "Max Mustermann",
    "account"      : "******2345",
    "created_at"   : 1349944973,
    "updated_at"   : 1349944973,
    "app_id"       : null,
    "is_recurring" : true,
    "is_usable_for_preauthorization" : true
}

Attributes

id: string
Unique identifier for this direct debit payment

client: client object / null

type: enum (creditcard, debit, paypal)

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 / null
App (ID) that created this payment or null if created by yourself

is_recurring: boolean
The payment is recurring (can be used more than once)

is_usable_for: boolean
The payment is usable for preauthorization

Payment object for direct debit payments (SEPA)

Example

{
    "id"           : "pay_917018675b21ca03c4fb",
    "type"         : "debit",
    "client"       : null,
    "code"         : "12345678",
    "holder"       :"Alex Tabo",
    "account"      :"*****9890",
    "iban"         :"DE1250010517******9890",
    "bic"          :"BENEDEPPYYY",
    "created_at"   : 1349944973,
    "updated_at"   : 1349944973,
    "app_id"       : null,
    "is_recurring" : true,
    "is_usable_for_preauthorization" : true
}

Attributes

id: string
Unique identifier for this direct debit payment

type: enum (creditcard, debit, paypal)

client: client object / null

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

iban: string
International Bank Account Number

bic: string
Business Identifier Code

created_at: integer
Unix-Timestamp for the creation date

updated_at: integer
Unix-Timestamp for the last update

app_id: string / null
App (ID) that created this payment or null if created by yourself

is_recurring: boolean
The payment is recurring (can be used more than once)

is_usable_for: boolean
The payment is usable for preauthorization

Payment Object for PayPal

Example

{
  "id": "pay_ff7136caa965a9a4e9b3c934",
  "type": "paypal",
  "client": null,
  "holder": "John Doe",
  "account": "john.doe@example.com",
  "created_at": 1432647580,
  "updated_at": 1432647582,
  "app_id": null,
  "is_recurring": false,
  "is_usable_for_preauthorization": false
}

Attributes

id: string
Unique identifier for this credit card payment

type: enum(creditcard,debit,paypal)

client: client object or null

holder: string
Name of the account holder

account: string
Email address 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.

is_recurring: boolean
Whether payment is recurring (can be used more than once).

is_usable_for_preauthorization: boolean
Whether payment is usable for preauthorization.

Create new Credit Card Payment

With token

Request

curl https://api.paymill.com/v2.1/payments \
  -u <YOUR_PRIVATE_KEY>: \
  -d "token=098f6bcd4621d373cade4e832627b4f6"
Paymill::Payment.create( token: '098f6bcd4621d373cade4e832627b4f6' )

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

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

payment_service = paymill_context.get_payment_service();
payment_with_token = payment_service.create(token='098f6bcd4621d373cade4e832627b4f6');

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

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

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

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,
        "is_recurring" : true,
        "is_usable_for_preauthorization" : true
    },
    "mode" : "test"
}

Note

  • You always need a token to create a new credit card payment
  • That Token is only usable one time afterwards please use the payment object

With token + client

Request

curl https://api.paymill.com/v2.1/payments \
  -u <YOUR_PRIVATE_KEY>: \
  -d "token=098f6bcd4621d373cade4e832627b4f6" \
  -d "client=client_88a388d9dd48f86c3136"
Paymill::Payment.create(
    token: '098f6bcd4621d373cade4e832627b4f6',
    client: 'client_88a388d9dd48f86c3136'
)

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

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

payment_service = paymill_context.get_payment_service();
payment_with_token_and_client = payment_service.create(
    token='098f6bcd4621d373cade4e832627b4f6',
    client_id='client_33baaf3ee3251b083420'
);

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

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

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

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,
        "is_recurring" : true,
        "is_usable_for_preauthorization" : true
    },
    "mode" : "test"
}

Attributes

token: string
Unique credit card token

client: client object / 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
  • That Token is only usable one time afterwards please use the payment object

Create new Debit Payment

With token

Request

curl https://api.paymill.com/v2.1/payments \
  -u <YOUR_PRIVATE_KEY>: \
  -d "token=12a46bcd462sd3r3care4e8336ssb4f5"
Paymill::Payment.create( token: '12a46bcd462sd3r3care4e8336ssb4f5' )

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.createWithToken(
    "12a46bcd462sd3r3care4e8336ssb4f5"
);

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

payment_service = paymill_context.get_payment_service();
payment_with_token = payment_service.create(token='12a46bcd462sd3r3care4e8336ssb4f5');

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

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

PaymentService paymentService = paymillContext.PaymentService;
Payment payment = paymentService.CreateWithTokenAsync(
    "12a46bcd462sd3r3care4e8336ssb4f5"
).Result;

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,
        "is_recurring" : true,
        "is_usable_for_preauthorization" : true
    },
    "mode" : "test"
}

With token + client

Request

curl https://api.paymill.com/v2.1/payments \
  -u <YOUR_PRIVATE_KEY>: \
  -d "token=12a46bcd462sd3r3care4e8336ssb4f5" \
  -d "client=client_88a388d9dd48f86c3136"
Paymill::Payment.create(
    token: '12a46bcd462sd3r3care4e8336ssb4f5',
    client: 'client_88a388d9dd48f86c3136'
)

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.createWithTokenAndClient(
   "12a46bcd462sd3r3care4e8336ssb4f5",
   "client_88a388d9dd48f86c3136"
);

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

payment_service = paymill_context.get_payment_service();
payment_with_token_and_client = payment_service.create(
    token='12a46bcd462sd3r3care4e8336ssb4f5',
    client_id='client_33baaf3ee3251b083420'
);

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

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

PaymentService paymentService = paymillContext.PaymentService;
Payment payment = paymentService.CreateWithTokenAndClientAsync(
    "12a46bcd462sd3r3care4e8336ssb4f5",
    "client_88a388d9dd48f86c3136"
).Result;

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,
        "is_recurring" : true,
        "is_usable_for_preauthorization" : true
    },
    "mode" : "test"
}

token: string
Unique direct debit token

client: client object / 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

Request

curl https://api.paymill.com/v2.1/payments/pay_3af44644dd6d25c820a8 \
  -u <YOUR_PRIVATE_KEY>
Paymill::Payment.find( 'pay_3af44644dd6d25c820a8' )

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

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

payment_service = paymill_context.get_payment_service();
payment_details = payment_service.detail(payment_with_token);

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

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

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

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,
        "is_recurring" : true,
        "is_usable_for_preauthorization" : true
    },
    "mode" : "test"
}

Returns data of a specific payment.

Attributes

id: string
Unique identifier for the payment

List Payments

Request

curl https://api.paymill.com/v2.1/payments \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Payment.all

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

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);
});

payment_service = paymill_context.get_payment_service();
payments_list = payment_service.list();

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

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

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

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,
            "is_recurring" : true,
            "is_usable_for_preauthorization" : true
        }
    ],
    "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

Request

curl https://api.paymill.com/v2.1/payments/pay_3af44644dd6d25c820a8 \
  -u <YOUR_PRIVATE_KEY>: \
  -X DELETE
payment = Paymill::Payment.find( 'pay_ea98515b29437b046207ea45' )
payment.delete

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

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

payment_service = paymill_context.get_payment_service();
paymentService.remove(payment_with_token);

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

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

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

Response

{
    "data":[

    ],
    "mode" : "test"
}

Deletes the specified payment.

Attributes

id: string
Unique identifier for the payment

Export Payment list

Request

curl https://api.paymill.com/v2.1/payments \
  -u <YOUR_PRIVATE_KEY>: \
  -H "Accept: text/csv"
The partial "snippets/ruby/samples/transactions/export_payments_list.rb" was not found, as such it will not be rendered.
The partial "snippets/java/samples/transactions/export_payments_list.java" was not found, as such it will not be rendered.
The partial "snippets/js/samples/transactions/export_payments_list.js" was not found, as such it will not be rendered.
The partial "snippets/python/samples/transactions/export_payments_list.py" was not found, as such it will not be rendered.
The partial "snippets/php/samples/transactions/export_payments_list.php" was not found, as such it will not be rendered.
The partial "snippets/net/samples/transactions/export_payments_list.cs" was not found, as such it will not be rendered.

Response

"id";"type";"card_type";"country";"expire_month";"expire_year";"card_holder";"last4";"updated_at";"created_at";"app_id";"client_id"
"pay_2311e5a076ab0b9c2cdb0399";"creditcard";"visa";"";"2";"2016";"test card holder";"1111";"1342427064";"1342427064";"";"client_33c8f8c13d759d00b144"

This function returns CSV separated by semicolons, encapsulated by double quotes, with a list of clients. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • card_type
  • created_at
  • type
  • updated_at

Available filters:

  • card_type
  • created_at
  • type
  • updated_at

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

Example

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

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 for this preauthorization

description string / null
Description for this preauthorization (max. 255 chars)

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 / null

client client object / null

created_at integer
Unix-Timestamp for the creation date

updated_at integer
Unix-Timestamp for the last update

app_id string / null
App (ID) that created this preauthorization or null if created by yourself

Create new Preauthorization

With token

Request

curl https://api.paymill.com/v2.1/preauthorizations \
  -u <YOUR_PRIVATE_KEY>: \
  -d "token=098f6bcd4621d373cade4e832627b4f6" \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "description=description example"
Paymill::Preauthorization.create(
    token: '098f6bcd4621d373cade4e832627b4f6',
    amount: 4200,
    currency: 'EUR',
    description: 'description example'
)

PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
Preauthorization preauthorization = preauthorizationService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    "description example"
);

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

preauthorization_service = paymill_context.get_preauthorization_service();
preauthorization_with_token = preauthorization_service.create_with_token(
    token='098f6bcd4621d373cade4e832627b4f6',
    amount=4200,
    currency='EUR',
    description='description example'
);

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

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

PreauthorizationService preauthorizationService = paymillContext.PreauthorizationService;

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

Response

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

With payment

Request

curl https://api.paymill.com/v2.1/preauthorizations \
  -u <YOUR_PRIVATE_KEY>: \
  -d "payment=pay_d43cf0ee969d9847512b" \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "description=description example"
payment = Paymill::Payment.create(token: '098f6bcd4621d373cade4e832627b4f6')

Paymill::Preauthorization.create(
    payment: payment.id,
    amount: 4200,
    currency: 'EUR',
    description: 'description example'
)

PaymentService paymentService = paymillContext.getPaymentService();
Payment payment = paymentService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6"
);
PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
Preauthorization preauthorization = preauthorizationService.createWithPayment(
    payment,
    4200,
    "EUR",
    "example description"
);

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

preauthorization_service = paymill_context.get_preauthorization_service();
preauthorization_with_payment = preauthorization_service.create_with_payment_id(
    payment_id ='pay_3af44644dd6d25c820a9',
    amount=4200,
    currency='EUR',
    description='description example'
);

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

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

PaymentService paymentService = paymillContext.PaymentService;

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

PreauthorizationService preauthorizationService = paymillContext.PreauthorizationService;
Preauthorization preauthorization = preauthorizationService.CreateWithPaymentAsync(
    payment,
    4200,
    "EUR",
    "description example"
).Result;

Response

{
    "data":{
        "id":"preauth_0b771c503680c341548e",
        "amount":"4200",
        "currency":"EUR",
        "description":"description example",
        "status":"closed",
        "livemode":false,
        "created_at":1349948920,
        "updated_at":1349948920,
        "app_id":null,
        "payment""<Object>",
        "client":"<Object>",
        "transaction":"<Object>"
    },
    "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 string
The identifier of a token

payment string
The identifier of a payment (only creditcard-object)

description string / null
Description for this preauthorization (max. 255 chars)

Preauthorization details

Request

curl https://api.paymill.com/v2.1/preauthorizations/preauth_31eb90495837447f76b7 \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Preauthorization.find('preauth_31eb90495837447f76b7')

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

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

preauthorization_service = paymill_context.get_preauthorization_service();
preauthorization_details = preauthorization_service.detail(preauthorization_with_token);

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

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

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

Response

{
    "data":{
        "id":"preauth_31eb90495837447f76b7",
        "amount":"4200",
        "currency":"EUR",
        "description":"description example",
        "status":"closed",
        "livemode":false,
        "created_at":1349948920,
        "updated_at":1349948920,
        "app_id":null,
        "payment""<Object>",
        "client":"<Object>",
        "transaction":"<Object>"
    },
    "mode":"test"
}
  - 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 Preauthrization

Request

curl https://api.paymill.com/v2.1/preauthorizations/preauth_31eb90495837447f76b7 \
  -u <YOUR_PRIVATE_KEY>: \
  -X DELETE
preauthorization = Paymill::Preauthorization.find('preauth_31eb90495837447f76b7')
preauthorization.delete

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

/* Not implemented yet */

preauthorization_service = paymill_context.get_preauthorization_service();
preauthorization_service.remove(preauthorization_with_token);

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

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

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

Response

{
    "data":[

    ],
    "mode" : "test"
}

This function deletes a preauthorization.

Attributes

id string
Unique identifier of this preauthorization

List Preauthrizations

Request

curl https://api.paymill.com/v2.1/preauthorizations \
  -u <YOUR_PRIVATE_KEY>:
The partial "snippets/ruby/samples/preauthorizations/list_preauthorizations.rb" was not found, as such it will not be rendered.
PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
PaymillList preauthorizations = preauthorizationService.list();

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);
});

preauthorization_service = paymill_context.get_preauthorization_service();
preauthorizations_list = preauthorization_service.list();

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

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

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

Response


{
    "data" : [
        {
            "id":"preauth_31eb90495837447f76b7",
            "amount":"4200",
            "currency":"EUR",
            "description":"description example",
            "status":"closed",
            "livemode":false,
            "created_at":1349948920,
            "updated_at":1349948920,
            "app_id":null,
            "payment""<Object>",
            "client":"<Object>",
            "transaction":"<Object>"
        }
    ],
    "data_count" : "1",
    "mode" : "test"
}
  - 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=``
  • `payment=``
  • `amount=[>|<] e.g. "300" or with prefix: ">300" or "<300"``
  • created_at=<timestamp> | <timestamp (from)>-<timestamp (to)>

Export Preauthorizations List

Request

curl https://api.paymill.com/v2.1/preauthorizations \
  -u <YOUR_PRIVATE_KEY>: \
  -H "Accept: text/csv"
# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

Response

"id";"amount";"currency";"description";"status";"livemode";"created_at";"updated_at";"app_id";"payment_id";"client_id";"transaction_id"
"preauth_31eb90495837447f76b7";"499";"EUR";"Subscription#sub_5dd7af6fa6d58c60a4e9";"preauth_subscription";"";"1342427064";"1342427064";"";"pay_2311e5a076ab0b9c2cdb0399";"client_33c8f8c13d759d00b144";""

This function returns CSV separated by semicolons, encapsulated by double quotes, with a list of preauthorizations. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • amount
  • created_at
  • updated_at

Available filters:

  • amount
  • client
  • created_at
  • payment
  • updated_at

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

Example

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

Sub objects

  - transaction.refunds returns refund object
  - 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 for this preauthorization

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)

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 preauthorization was issued while being in live mode or not

refunds: list refund objects or null

client: client object or null

currency: string
ISO 4217 formatted currency code

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

is_fraud: boolean
The transaction is marked as fraud or not

invoices: list
PAYMILL invoice where the transaction fees are charged or null

items: list shopping cart items or null
Shopping cart items purchased with this transaction.

shipping_address: address object or null
Shipping address for this transaction.

billing_address: address object or null
Billing address for this transaction.

app_id: string or null
App (ID) that created this transaction or null if created by yourself

preauthorization: preauthorizations-object or null

fees: list
App fees or null

payment: payment object for credit card / directdebit-object or null

mandate_reference: string or null
SEPA mandate reference, can be optionally specified for direct debit transactions. If specified for other payment methods, it has no effect but must still be valid. If specified, the string must not be empty, can be up to 35 characters long and may contain: digits 0-9, letters a-z A-Z, allowed special characters: ‘ , . : + - / ( ) ?

is_refundable: boolean
The transaction is refundable or not

is_markable_as_fraud: boolean
The transaction is markable is fraud or not

Fee Object

Attributes

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 https://api.paymill.com/v2.1/transactions \
  -u <YOUR_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "payment=pay_2f82a672574647cd911d" \
  -d "description=Test Transaction"
payment = Paymill::Payment.create(token: '098f6bcd4621d373cade4e832627b4f6')
transaction = Paymill::Transaction.create(
    payment: payment,
    amount: 4200,
    currency: 'EUR',
    description: 'Test Transaction'
)

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

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);
});

transaction_service = paymill_context.get_transaction_service();
transaction_with_payment = transaction_service.create_with_payment_id(
    payment_id='pay_3af44644dd6d25c820a9',
    amount=4200,
    currency='EUR',
    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.PaymentService;
Payment payment = paymentService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6"
).Result;
TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithTokenAsync(
    payment,
    4200,
    "EUR",
    "Test Transaction"
).Result;

Response

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

With token

Request

curl https://api.paymill.com/v2.1/transactions \
  -u <YOUR_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "token=098f6bcd4621d373cade4e832627b4f6" \
  -d "description=Test Transaction"
Paymill::Transaction.create(
    token: '098f6bcd4621d373cade4e832627b4f6',
    amount: 4200,
    currency: 'EUR',
    description: 'Test Transaction'
)

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

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

transaction_service = paymill_context.get_transaction_service();
transaction_with_token = transaction_service.create_with_token(
    token='098f6bcd4621d373cade4e832627b4f6',
    amount=4200,
    currency='EUR',
    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.TransactionService;
Transaction transaction = transactionService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    "Test Transaction"
).Result;

Response

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

With client and payment

Request

curl https://api.paymill.com/v2.1/transactions \
  -u <YOUR_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "client=client_c781b1d2f7f0f664b4d9" \
  -d "payment=pay_a818b847db6ce5ff636f" \
  -d "description=Test Transaction"
client = Paymill::Client.create(email: 'mail@example.com')
payment = Paymill::Payment.create(
    token: '098f6bcd4621d373cade4e832627b4f6',
    client: client
)

Paymill::Transaction.create(
    payment: payment,
    client: client,
    amount: 4200,
    currency: 'EUR'
)

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

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);
});

transaction_service = paymill_context.get_transaction_service();
transaction_with_client_and_payment = transaction_service.create_with_payment_id(
    payment_id='pay_3af44644dd6d25c820a9',
    amount=4200, currency='EUR',
    description='Test Transaction',
    client_id='client_33baaf3ee3251b083420'
);

$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.TransactionService;
Transaction transaction = transactionService.CreateWithPaymentAndClientAsync(
    "pay_a818b847db6ce5ff636f",
    "client_c781b1d2f7f0f664b4d9",
    4200,
    "EUR"
).Result;

Response

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

With preauthorization

Request

curl https://api.paymill.com/v2.1/transactions \
  -u <YOUR_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "preauthorization=preauth_ec54f67e52e92051bd65" \
  -d "description=Test Transaction"
preauthorization = Paymill::Preauthorization.create(
    token: '098f6bcd4621d373cade4e832627b4f6',
    amount: 4200,
    currency: 'EUR'
)
transaction = Transaction.create(
    preauthorization: preauthorization,
    amount: 4200,
    currency: 'EUR'
)

PreauthorizationService preauthorizationService = paymillContext.getPreauthorizationService();
Preauthorization preauthorization = preauthorizationService.createWithToken(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR"
).getPreauthorization();

TransactionService transactionService = paymillContext.getTransactionService();
Transaction transaction = this.transactionService.createWithPreauthorization(
    preauthorization,
    4200,
    "EUR",
    "Test Transaction"
);

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);
});

transaction_service = paymill_context.get_transaction_service();
transaction_with_preauthorization = transaction_service.create_with_preauthorization_id(
    preauthorization_id='preauth_ec54f67e52e92051bd65',
    amount=4200, currency='EUR',
    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.PreauthorizationService;
Preauthorization preauthorization = preauthorizationService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR"
).Result;

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

Response

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

With app fee

Request

curl https://api.paymill.com/v2.1/transactions \
  -u <YOUR_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"
Paymill::Transaction.create(
    token: '098f6bcd4621d373cade4e832627b4f6',
    amount: 4200, currency: 'EUR',
    description: 'Test Transaction',
    fee_amount: 4200,
    fee_payment: 'pay_a818b847db6ce5ff636f',
    fee_currency: 'EUR'
)

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

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);
});

transaction_service = paymill_context.get_transaction_service();
transaction_with_token = transaction_service.create_with_token(
    token='098f6bcd4621d373cade4e832627b4f6',
    amount=4200, currency='EUR',
    description='Test Transaction',
    fee_amount=4200,
    fee_payment_id='pay_3af44644dd6d25c820a8',
    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.Amount =  420;
fee.Payment = "pay_3af44644dd6d25c820a8";
TransactionService transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithTokenAndFeeAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    fee
).Result;

Response

{
    "data" : {
    "id" : "tran_ca3e7d41fb16d0157a99",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : "Test Transaction",
        "livemode" : false,
        "refunds" : null,
        "client" : "<Object>",
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "is_fraud" : false,
        "invoices" : [],
        "items": [ "<Object>", "<Object>", "<Object>" ],
        "shipping_address": "<Object>",
        "billing_address": "<Object>"
        "app_id" : null,
        "preauthorization" : null,
        "fees" : [
          {
            "type" : "application",
            "application" : "app_1d70acbf80c8c35ce83680715c06be0",
            "payment" : "pay_3af44644dd6d25c820a8",
            "amount" : 420,
            "currency" :  "EUR",
            "billed_at" :  null
          }
        ],
        "payment" : "<Object>",
        "is_refundable" : true,
        "is_markable_as_fraud" : true
    },
    "mode" : "test"
}
  - transaction.refunds returns refund object
  - 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).

fee_currency string / 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

With transaction id

Request

curl https://api.paymill.com/v2.1/transactions/tran_023d3b5769321c649435 \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Transaction.find('tran_023d3b5769321c649435')

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

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

transaction_service = paymill_context.get_transaction_service();
transaction_details = transaction_service.detail(transaction_with_token);

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

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

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

Response

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

With SLV

Request

curl https://api.paymill.com/v2.1/transactions/slv_4125875679 \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Transaction.find('tran_023d3b5769321c649435')

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

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

transaction_service = paymill_context.get_transaction_service();
transaction_details = transaction_service.detail(transaction_with_token);

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

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

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

Response

{
    "data" : {
        "id" : "tran_023d3b5769321c649435",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : "Test Transaction",
        "livemode" : false,
        "refunds" : null,
        "client" : "<Object>",
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "is_fraud" : false,
        "invoices" : [],
        "items": [ "<Object>", "<Object>", "<Object>" ],
        "shipping_address": "<Object>",
        "billing_address": "<Object>"
        "app_id" : null,
        "preauthorization" : null,
        "fees" : [],
        "payment" : "<Object>",
        "is_refundable" : true,
        "is_markable_as_fraud" : true
    },
    "mode" : "test"
}
  - transaction.refunds returns refund object
  - 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 or the unique slv number. You can find the ID in the response of the previous request (or the slv number on your account statement). 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

slv number string
Unique 10 character long slv number of this transaction

Update Transaction

Request

curl https://api.paymill.com/v2.1/transactions/tran_023d3b5769321c649435 \
  -u <YOUR_PRIVATE_KEY>:  \
  -d "description=My updated transaction description" \
  -X PUT
The partial "snippets/ruby/samples/transactions/update_transaction.rb" was not found, as such it will not be rendered.
The partial "snippets/java/samples/transactions/update_transaction.java" was not found, as such it will not be rendered.
The partial "snippets/js/samples/transactions/update_transaction.js" was not found, as such it will not be rendered.
The partial "snippets/python/samples/transactions/update_transaction.py" was not found, as such it will not be rendered.
The partial "snippets/php/samples/transactions/update_transaction.php" was not found, as such it will not be rendered.
The partial "snippets/net/samples/transactions/update_transaction.cs" was not found, as such it will not be rendered.

Response

{
    "data" : {
        "id" : "tran_023d3b5769321c649435",
        "amount" : "4200",
        "origin_amount" : 4200,
        "status" : "closed",
        "description" : "My updated transaction description",
        "livemode" : false,
        "refunds" : null,
        "client" : "<Object>",
        "currency" : "EUR",
        "created_at" : 1349946151,
        "updated_at" : 1349946151,
        "response_code" : 20000,
        "short_id" : "0000.1212.3434",
        "is_fraud" : false,
        "invoices" : [],
        "items": [ "<Object>", "<Object>", "<Object>" ],
        "shipping_address": "<Object>",
        "billing_address": "<Object>"
        "app_id" : null,
        "preauthorization" : null,
        "fees" : [],
        "payment" : "<Object>",
        "is_refundable" : true,
        "is_markable_as_fraud" : true
    },
    "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

Request

curl https://api.paymill.com/v2.1/transactions \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Transaction.all()

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

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);
});

transaction_service = paymill_context.get_transaction_service();
transactions_list = transaction_service.list();

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

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

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

Response

{
    "data" : [
        {
            "id" : "tran_03bb8f63d5278f723ced",
            "amount" : "4200",
            "origin_amount" : 4200,
            "status" : "closed",
            "description" : "ShoppingcartID 873242",
            "livemode" : false,
            "refunds" : null,
            "client" : "<Object>",
            "currency" : "EUR",
            "created_at" : 1349946151,
            "updated_at" : 1349946151,
            "response_code" : 20000,
            "short_id" : "0000.1212.3434",
            "is_fraud" : false,
            "invoices" : [],
            "items": [ "<Object>", "<Object>", "<Object>" ],
            "shipping_address": "<Object>",
            "billing_address": "<Object>"
            "app_id" : null,
            "preauthorization" : null,
            "fees" : [],
            "payment" : "<Object>",
            "is_refundable" : true,
            "is_markable_as_fraud" : true
        },
        {
            "id" : "tran_5e3105d4c2f34fe9d1f",
            "amount" : "5699",
            "origin_amount" : 5699,
            "status" : "closed",
            "description" : "ShoppingcartID 873243",
            "livemode" : false,
            "refunds" : null,
            "client" : "<Object>",
            "currency" : "EUR",
            "created_at" : 1349953847,
            "updated_at" : 1349953847,
            "response_code" : 20000,
            "short_id" : "0000.1212.3434",
            "is_fraud" : false,
            "invoices" : [],
            "items": [ "<Object>", "<Object>", "<Object>" ],
            "shipping_address": "<Object>",
            "billing_address": "<Object>"
            "app_id" : null,
            "preauthorization" : null,
            "fees" : [],
            "payment" : "<Object>",
            "is_refundable" : true,
            "is_markable_as_fraud" : true
        }
    ],
    "data_count" : "2",
    "mode" : "test"
}
  - transaction.refunds returns refund object
  - 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
  • last4=<integer> last 4 digits of the credit card
  • short_id=<string>

Available status for filters:

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

Export Transactions List

Request

curl https://api.paymill.com/v2.1/transactions \
  -u <YOUR_PRIVATE_KEY>: \
  -H "Accept: text/csv"
# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

Response

"id";"amount";"origin_amount";"status";"description";"livemode";"currency";"created_at";"updated_at";"response_code";"short_id";"is_fraud";"app_id";"client_id";"payment_id";"preauthorization_id";"invoices";"fees"
"tran_494d384289fbaa1aa342a35723f7";"599";"599";"closed";"Test Transaction";"";"EUR";"1342427064";"1342427064";"20000";"7357.7357.7357";"";"";"client_53396385b7438a6a5cc2";"pay_2bbe85119a00f22d061eb752";;"";""

This function returns CSV separated by semicolons, encapsulated by double quotes, with a list of transactions. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • amount
  • created_at
  • currency
  • description
  • status
  • updated_at

Available filters:

  • amount
  • client
  • created_at
  • currency
  • description
  • last4
  • payment
  • status
  • updated_at

Refunds

Refund object

Example

{
    "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
}

Sub objects

  - refund.transaction returns a transaction object

Attributes

id: string
Unique identifier for 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 / null
App (ID) that created this refund or null if created by yourself

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

Refund Transaction

Request

curl https://api.paymill.com/v2.1/refunds/tran_023d3b5769321c649435 \
  -u <YOUR_PRIVATE_KEY>: \
  -d "amount=4200"
transaction = Paymill::Transaction.create(
    token: '098f6bcd4621d373cade4e832627b4f6',
    amount: 4200,
    currency: 'USD'
)

Paymill::Refund.create(
    transaction,
    amount: 4200,
    description: 'Sample Description'
)

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

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

refund_service = paymill_context.get_refund_service();
refund_transaction = refund_service.refund_transaction(
    transaction_id='tran_ca3e7d41fb16d0157a99',
    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 transactionService = paymillContext.TransactionService;
Transaction transaction = transactionService.CreateWithTokenAsync(
    "098f6bcd4621d373cade4e832627b4f6",
    4200,
    "EUR",
    "For refund"
).Result;
RefundService refundService = paymillContext.RefundService;
Refund refund = refundService.RefundTransactionAsync(
    transaction,
    4200,
    "Sample Description"
).Result;

Response

{
    "data" : {
        "id" : "refund_70392dc6a734a8233130",
        "amount" : "4200",
        "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 object
  - 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 / null
Additional description for this refund

Refund Details

Request

curl https://api.paymill.com/v2.1/refunds/refund_87bc404a95d5ce616049 \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Refund.find('refund_87bc404a95d5ce616049')

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

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

refund_service = paymill_context.get_refund_service();
refund_details = refund_service.detail(refund_transaction)

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

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

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

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

Request

curl https://api.paymill.com/v2.1/refunds \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Refund.all()

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

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);
});

refund_service = paymill_context.get_refund_service();
refunds_list = refund_service.list();

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

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

RefundService refundService = paymillContext.RefundService;
PaymillList refunds = refundService.ListAsync;

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

Export Refunds List

Request

curl https://api.paymill.com/v2.1/refunds \
  -u <YOUR_PRIVATE_KEY>: \
  -H "Accept: text/csv"
# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

Response

"id";"amount";"status";"description";"livemode";"created_at";"updated_at";"response_code";"app_id";"transaction_id"
"refund_a7c4a0b9d09d9833a5d5";"2222";"refunded";"";"";"1342427064";"1342427064";"20000";"";"tran_27a814bfbc7f3af580143713f80e"

This function returns CSV separated by semicolons, encapsulated by double quotes, with a list of refunds. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • amount
  • created_at
  • updated_at

Available filters:

  • amount
  • client
  • created_at
  • transaction
  • updated_at

Checksums

Checksum validation is a simple method to ensure the integrity of transferred data. Basically, we generate a hash out of the given parameters and your private API key. If you send us a request with transaction data and the generated checksum, we can easily validate the data. To make the checksum computation as easy as possible we provide this endpoint for you.

For transactions that are started client-side, e.g. PayPal checkout, it is required to first create a checksum on your server and then provide that checksum when starting the transaction in the browser. The checksum needs to contain all data required to subsequently create the actual transaction.

Create new Checksum

Request

curl https://api.paymill.com/v2.1/checksums \
  -u "<YOUR_PRIVATE_KEY>:" \
  -d "checksum_type=paypal" \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "description=Test Transaction" \
  -d "return_url=https://www.example.com/store/checkout/result" \
  -d "cancel_url=https://www.example.com/store/checkout/retry"

Response

{
    "id":"chk_9fc0af0f6107706e4a4b8d7e71b5",
    "checksum":"edc26c087697a277230539da0e89b1ab96b93bc635e980c78573de6be3041689c77401bc299aa8c98cda33abe6b097f3df009feb495b19215f407c9655401c1b",
    "data":"amount=4200&currency=EUR&description=Test+Transaction&return_url=https%3A%2F%2Fwww.example.com%2Fstore%2Fcheckout%2Fresult&cancel_url=https%3A%2F%2Fwww.example.com%2Fstore%2Fcheckout%2Fretry",
    "type":"paypal",
    "app_id":null,
    "created_at":1433248940,
    "updated_at":1433248940
}

Attributes

id: string
ID of this checksum

checksum_type: enum(paypal)
Type of request verified by this checksum

amount: string
Formatted amount of this transaction.

currency: array
ISO 4217 formatted currency code

description: array
A short description for the transaction

return_url: string URL to redirect customers to after checkout has completed. Transaction status will be closed, failed or pending.
Mandatory for client-side transactions, e.g. PayPal

cancel_url: string
URL to redirect customers to after they have canceled the checkout. As a result, there will be no transaction.
Mandatory for client-side transactions, e.g. PayPal

items: list shopping cart items or null
Shopping cart items purchased with this transaction.

shipping_address: address object or null
Shipping address for this transaction.

billing_address: address object or null
Billing address for this transaction.

app_id: string or null
App (ID) that created this refund or null if created by yourself.

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.

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

Example

{
    "id"           :  "client_88a388d9dd48f86c3136",
    "email"        :  "lovely-client@example.com",
    "description"  :  null,
    "created_at"   :  1340199740,
    "updated_at"   :  1340199760,
    "payment"      :  "[ <Object>, ... ] or null",
    "subscription" :  "[ <Object>, ... ] or null",
    "app_id"       :  null
}

Sub objects

  - client.payment returns payment objects for credit card or direct debit
  - client.subscription returns subscription objects or null

Attributes

id: string
Unique identifier of this client

email: string / null
Mail address of this client

description: string / 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
credit card or direct debit

subscription: list / null
subscriptions objects

app_id: string / null
App (ID) that created this client or null if created by yourself

Create new Client

Request

curl https://api.paymill.com/v2.1/clients \
  -u <YOUR_PRIVATE_KEY>: \
  -d "email=lovely-client@example.com" \
  -d "description=Lovely Client"
Paymill::Client.create(
    email: 'lovely-client@example.com',
    description: 'Lovely Client'
)

ClientService clientService = paymillContext.getClientService();
Client client = clientService.createWithEmailAndDescription(
    "lovely-client@example.com",
    "Lovely Client"
);

pm.clients.create("lovely-client@example.com", "Lovely Client").then(function(client) {
    console.log("client:" + client.id);
}, function(error) {
    console.log("couldnt get client:" + error);
});

client_service = paymill_context.get_client_service();
client = client_service.create(email='lovely-client@example.com');

$client = new Paymill\Models\Request\Client();
$client->setEmail('max.mustermann@example.com')
       ->setDescription('Lovely Client')

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

ClientService clientService = paymillContext.ClientService;
Client client = clientService.CreateWithEmailAndDescriptionAsync(
    "lovely-client@example.com",
    "Lovely Client"
).Result;

Response

{
    "data" : {
        "id"           : "client_88a388d9dd48f86c3136",
        "email"        : "lovely-client@example.com",
        "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 subscription objects or null

This function creates a client object.

Attributes

email: string / null
Mail address of the client, is optional if the transaction creates an user itself

description: string / null
Description for the client

Client details

Request

curl https://api.paymill.com/v2.1/clients/client_88a388d9dd48f86c3136 \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Client.find('client_88a388d9dd48f86c3136')

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

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

client_service = paymill_context.get_client_service();
client_details = client_service.detail(client)

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

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

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

Response

{
    "data" : {
        "id"           : "client_88a388d9dd48f86c3136",
        "email"        : "client@example.com",
        "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 subscription objects or null

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

Request

curl https://api.paymill.com/v2.1/clients/client_88a388d9dd48f86c3136 \
  -u <YOUR_PRIVATE_KEY>: \
  -d "email=lovely-client@example.com" \
  -d "description=My Lovely Client" \
  -X PUT
client = Paymill::Client.find('client_88a388d9dd48f86c3136')
client.email = 'lovely-client@example.com'
client.description = 'My Lovely Client'
client.update

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

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);
});

client_service = paymill_context.get_client_service();
client.email = 'lovely-client-updated-email@example.com';
client_service.update(client);

$client = new Paymill\Models\Request\Client();
$client->setId('client_88a388d9dd48f86c3136')
       ->setEmail('updated-client@example.com')
       ->setDescription('Updated Client');

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

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

Response

{
    "data" : {
        "id"           : "client_88a388d9dd48f86c3136",
        "email"        : "lovely-client@example.com",
        "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 subscription objects or null

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 / null
Mail address of the client

description: string / null
Description for the client

Remove Client

Request

curl https://api.paymill.com/v2.1/clients/client_88a388d9dd48f86c3136 \
  -u <YOUR_PRIVATE_KEY>: \
  -X DELETE
client = Paymill::Client.find('client_88a388d9dd48f86c3136')
client.delete

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

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

client_service = paymill_context.get_client_service();
client_service.remove(client);

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

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

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

Response

{
    "data": null
    "mode": "test"
}

Sub objects

  - client.payment returns payment objects for credit card or direct debit
  - client.subscription returns subscription objects or null

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

Attributes

id: string
Unique identifier for the client

List Clients

Request

curl https://api.paymill.com/v2.1/clients \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Client.all

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

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);
});

client_service = paymill_context.get_client_service();
clients_list = client_service.list();

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

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

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

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 subscription objects or null

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 Clients List

Request

curl https://api.paymill.com/v2.1/clients \
  -u <YOUR_PRIVATE_KEY>: \
  -H "Accept: text/csv"
# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

Response

"id";"email";"description";"app_id";"updated_at";"created_at";"payment";"subscription"
"client_33c8f8c13d759d00b144";"testclient@paymill.de";"test client";"";"1342427064";"1342427064";"pay_2311e5a076ab0b9c2cdb0399";"sub_c84aadd0c1c7529158ee,sub_c36362f70bb78d53e145,sub_11cc72a3a759d5ce7f47"

This function returns CSV separated by semicolons, encapsulated by double quotes, with a list of clients. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • created_at
  • description
  • email
  • updated_at

Available filters:

  • created_at
  • description=<string>
  • email=<email>
  • offer=<offer id>
  • payment=<payment id>
  • subscription=<subscription id>
  • updated_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

Example

{
    "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
}

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 / 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: subscription_count
Attributes: (integer) if zero, else (string) active, (integer) if zero, else (string) inactive

app_id: string / null
App (ID) that created this client or null if created by yourself

Create new Offer

Request

curl https://api.paymill.com/v2.1/offers \
  -u <YOUR_PRIVATE_KEY>: \
  -d "amount=4200" \
  -d "currency=EUR" \
  -d "interval=1 WEEK" \
  -d "name=Nerd Special"
Paymill::Offer.create(
    amount: 4200,
    currency: 'EUR',
    interval: '1 MONTH',
    name: 'Nerd Special',
    trial_period_days: 0
)

OfferService offerService = paymillContext.getOfferService();
Offer offer = offerService.create(
    4200,
    "EUR",
    "1 WEEK",
    "Nerd Special",
    0
);

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

offer_service = paymill_context.get_offer_service();
offer = offer_service.create(
    amount=4200,
    currency='EUR',
    interval='1 WEEK',
    'Nerd Special',
    0
);

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

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

OfferService offerService = paymillContext.OfferService;

Offer offer = offerService.CreateAsync(
    4200,
    "EUR",
    Interval.period(1, Interval.TypeUnit.WEEK),
    "Nerd Special",
    0
).Result;

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 Centre

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

Offer details

Request

curl https://api.paymill.com/v2.1/offers/offer_40237e20a7d5a231d99b \
  -u <YOUR_PRIVATE_KEY>: \
Paymill::Offer.find('offer_40237e20a7d5a231d99b')

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

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

offer_service = paymill_context.get_offer_service();
offer_details = offer_service.detail(offer);

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

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

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

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

Request

curl https://api.paymill.com/v2.1/offers/offer_40237e20a7d5a231d99b \
  -u <YOUR_PRIVATE_KEY>: \
  -d "name=Extended Special" \
  -d "interval=1 MONTH" \
  -d "amount=3333" \
  -d "currency=USD" \
  -d "trial_period_days=33" \
  -d "update_subscriptions=true" \
  -X PUT
offer = Paymill::Offer.find('offer_40237e20a7d5a231d99b')

offer.name = 'Extended Special'
offer.interval = '1 MONTH'
offer.currency = 'USD'
offer.amount = '3333'

offer.update( update_subscriptions: true )

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

offer.setName("Extended Special");
offer.setInterval("1 MONTH")
offer.setAmount(3333);
offer.setCurrency("USD");
offer.setTrialPeriodDays(33);

boolean updateSubscriptions=true;
offerService.update( offer,updateSubscriptions );

pm.offers.detail("offer_40237e20a7d5a231d99b").then(function(offer) {
    offer.name = "Extended Special";
    return pm.offers.update(offer);
}).then(function(updatedOffer) {
    console.log("updated offer:" + updatedOffer.description);
}, function(error) {
    console.log("couldnt update offer:" + error);
});

offer_service = paymill_context.get_offer_service();
offer.name = 'Extended Special';
offer.interval = '1 MONTH';
offer.amount = 3333;
offer.currency = 'USD';
offer.trial_period_days = '33';

offer_service.update(offer, true);

$offer = new Paymill\Models\Request\Offer();
$offer->setId('offer_40237e20a7d5a231d99b')
      ->setName('Extended Special')
      ->setInterval('1 MONTH')
      ->setAmount(3333)
      ->setCurrency('USD')
      ->setTrialPeriodDays(33)
      ->updateSubscriptions(true);

$response = $request->update($offer)

OfferService offerService = paymillContext.OfferService;

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

offer.Name = "Extended Special";
offer.Interval = Interval.period(1, Interval.TypeUnit.MONTH);
offer.Amount = 3333;
offer.Currency = "USD";
offer.TrialPeriodDays  = 33;

boolean updateSubscriptions = true;

Offer updatedOffer = offerService.UpdateAsync(offer, updateSubscriptions ).Result;

Response

{
    "data" : {
        "id" : "offer_40237e20a7d5a231d99b",
        "name" : "Extended Special",
        "amount" : 3333,
        "currency": "USD",
        "interval" : "1 MONTH",
        "trial_period_days" : 33,
        "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: integer
Your trial period in number of days (optional)

update_subscriptions: boolean Definition, if all related subscriptions also should be updated

Remove Offer

Request

curl https://api.paymill.com/v2.1/offers/offer_40237e20a7d5a231d99b \
  -u <YOUR_PRIVATE_KEY>: \
  -d "remove_with_subscriptions=false" \
  -X DELETE
# with subscriptions:
offer = Paymill::Offer.find('offer_40237e20a7d5a231d99b')
offer.delete_with_subscriptions()

# without subscriptions:
offer = Paymill::Offer.find('offer_40237e20a7d5a231d99b')
offer.delete_without_subscriptions()

OfferService offerService = paymillContext.getOfferService();
boolean removeWithSubscriptions = true;
offerService.delete( "offer_40237e20a7d5a231d99b", removeWithSubscriptions );

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

offer_service = paymill_context.get_offer_service();
offer_service.remove(offer);

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

$response = $request->delete($offer)

OfferService offerService = paymillContext.OfferService;
boolean removeWithSubscriptions = true;
Boolean result = offerService.DeleteAsync(
    "offer_40237e20a7d5a231d99b",
    removeWithSubscriptions
).Result;

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

Request

curl https://api.paymill.com/v2.1/offers \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Offer.all()

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

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);
});

offer_service = paymill_context.get_offer_service();
offers_list = offer_service.list();

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

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

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

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

Export Offers List

Request

curl https://api.paymill.com/v2.1/offers \
  -u <YOUR_PRIVATE_KEY>: \
  -H "Accept: text/csv"
  # Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

Response

"id";"name";"amount";"currency";"interval";"trial_period_days";"created_at";"updated_at";"subscription_count_active";"subscription_count_inactive";"app_id"
"offer_1a5d80dc75db9b5c0c64";"Example Offer";"499";"EUR";"3 WEEK";"22";"1342427064";"1342427064";"1";"8";""

This function returns CSV separated by semicolons, encapsulated by double quotes, with a list of clients. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • amount
  • created_at
  • currency
  • interval
  • name
  • trial_period_days
  • updated_at

Available filters:

  • amount
  • created_at
  • currency
  • interval
  • name
  • trial_period_days
  • updated_at

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

Example

{
  "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",
  "mandate_reference" : null,
  "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 / null
a one-time amount in cents, will charge once only

currency: _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 / null
name of the subscription

trial_start: integer / null
Unix-Timestamp for the trial period start

trial_end: integer / null
Unix-Timestamp for the trial period end

period_of_validity: string / null
limit the validity of the subscription, format: integer MONTH | YEAR | WEEK | DAY

end_of_period: Unix-Timestamp / 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 / null
Unix-Timestamp for the cancel date

payment: payment object for credit card / payment object for direct debit
payment object for credit card or payment object for direct debit

mandate_reference: string or null
SEPA mandate reference, can be optionally specified for direct debit transactions. If specified for other payment methods, it has no effect but must still be valid. If specified, the string must not be empty, can be up to 35 characters long and may contain digits 0-9, letters a-z A-Z, allowed special characters: ‘ , . : + - / ( ) ?

client: _client object
client object

app_id: string / 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"

Create new Subscription

Without an offer

Request

curl https://api.paymill.com/v2.1/subscriptions \
  -u <YOUR_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"
client = Paymill::Client.create(email: 'client@example.com')
payment = Paymill::Payment.create(token: '098f6bcd4621d373cade4e832627b4f6', client: client)

Paymill::Subscription.create(
    payment: payment,
    client: client,
    name: 'Example Subscription',
    amount: 3000,
    currency: 'EUR',
    interval: '1 week,monday',
    period_of_validity: '2 YEAR',
    start_at: 2.days.from_now
)

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
subscriptionService.create( Subscription.create(
    "pay_5e078197cde8a39e4908f8aa",
    3000,
    "EUR",
    Interval.periodWithChargeDay( 1, Unit.WEEK, Weekday.MONDAY )
    )
    .withName( "Example Subscription" )
    .withPeriodOfValidity( Interval.period( 2, Unit.YEAR ) )
    .withStartDate( new Date( 1400575533 ) )
);

pm.subscriptions.fromParams("pay_5e078197cde8a39e4908f8aa",3000,"EUR","1 week,monday")
.withClient( "client_81c8ab98a8ac5d69f749" )
.withName( "Example Subscription" )
.withPeriodOfValidity( "2 YEAR" )
.withStartDate( new Date(1400575533))
.create().then( function(subscription) {
    console.log("created subscription:" + subscription.id);
}, function(error) {
    console.log("couldnt create subscription:" + error);
});

subscription_service = paymill_context.get_subscription_service();
subscription_without_offer = subscription_service.create_with_amount(
    payment_id='pay_5e078197cde8a39e4908f8aa',
    amount=3OOO,
    currency='EUR',
    interval='1 WEEK,MONDAY'
);

$subscription = new Paymill\Models\Request\Subscription();
$subscription->setClient('client_81c8ab98a8ac5d69f749')
             ->setAmount(3000);
             ->setPayment('pay_5e078197cde8a39e4908f8aa');
             ->setCurrency('EUR');
             ->setInterval('1 week,monday');
             ->setName('Example Subscription');
             ->setPeriodOfValidity('2 YEAR');
             ->setStartAt('1400575533');

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

SubscriptionService subscriptionService = paymillContext.SubscriptionService;

subscriptionService.CreateAsync( Subscription.Create(
    "pay_5e078197cde8a39e4908f8aa",
    3000,
    "EUR",
    Interval.periodWithChargeDay( 1, Interval.TypeUnit.WEEK, Interval.Weekday.MONDAY ) )
.WithName( "Example Subscription" )
.WithPeriodOfValidity( Interval.period( 2, Interval.TypeUnit.YEAR ) )
.WithStartDate(DateTime.Now.AddDays(5)
);

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"
}

With an offer

Request

curl https://api.paymill.com/v2.1/subscriptions \
  -u <YOUR_PRIVATE_KEY>: \
  -d "client=client_64b025ee5955abd5af66" \
  -d "offer=offer_40237e20a7d5a231d99b" \
  -d "payment=pay_95ba26ba2c613ebb0ca8" \
  -d "period_of_validity=2 YEAR" \
  -d "start_at=1400575533"
payment = Paymill::Payment.create(token: '098f6bcd4621d373cade4e832627b4f6')
offer = Paymill::Offer.create(
    amount: 3333,
    currency: 'EUR',
    interval: '1 WEEK',
    name: 'Nerd Special',
    trial_period_days: 30
    )

Paymill::Subscription.create(
    payment: payment,
    offer: offer,
    period_of_validity: '2 YEAR',
    start_at: 2.days.from_now
)

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
subscriptionService.create( Subscription.create(
    "pay_95ba26ba2c613ebb0ca8",
    "offer_40237e20a7d5a231d99b"
).withPeriodOfValidity( Interval.period( 2, Unit.YEAR ) )
.withStartDate( new Date(1400575533) )
);

pm.subscriptions.fromOffer("pay_95ba26ba2c613ebb0ca8","offer_40237e20a7d5a231d99b")
.withClient( "client_64b025ee5955abd5af66" )
.withName( "Example Subscription" )
.withPeriodOfValidity( "2 YEAR" )
.withStartDate( new Date(1400575533)).create().then( function(subscription) {
    console.log("created subscription:" + subscription.id);
}, function(error) {
    console.log("couldnt create subscription:" + error);
});

subscription_service = paymill_context.get_subscription_service();
subscription_with_an_offer = subscription_service.create_with_offer_id(
    payment_id='pay_3af44644dd6d25c820a9',
    offer_id='offer_bb33ea77b942f570997b'
);

$subscription = new Paymill\Models\Request\Subscription();
$subscription->setClient('client_81c8ab98a8ac5d69f749')
             ->setOffer('offer_40237e20a7d5a231d99b');
             ->setPayment('pay_5e078197cde8a39e4908f8aa');
             ->setPeriodOfValidity('2 YEAR');
             ->setStartAt(1400575533);

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

SubscriptionService subscriptionService = paymillContext.SubscriptionService;

subscriptionService.CreateAsync( Subscription.Create(
    "pay_95ba26ba2c613ebb0ca8",
    "offer_40237e20a7d5a231d99b" )
.WithPeriodOfValidity( Interval.period( 2, Interval.TypeUnit.YEAR ) )
.WithStartDate( DateTime.Now.AddDays(5) )
);

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"
}

With offer and different values

Request

curl https://api.paymill.com/v2.1/subscriptions \
  -u <YOUR_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"
payment = Paymill::Payment.create(token: '098f6bcd4621d373cade4e832627b4f6')
offer = Paymill::Offer.create(
    amount: 4200,
    currency: 'EUR',
    interval: '1 MONTH',
    name: 'Nerd Special',
    trial_period_days: 30
)

Paymill::Subscription.create(
    payment: payment,
    offer: offer,
    amount: 3000,
    currency: 'EUR',
    interval: '1 week, monday',
    name: 'Example Subscription',
    period_of_validity: '2 YEAR',
    start_at: 2.days.from_now
)

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
subscriptionService.create( Subscription.create(
    "pay_95ba26ba2c613ebb0ca8",
    "offer_40237e20a7d5a231d99b"
).withAmount( 3000 )
.withCurrency( "EUR" )
.withInterval( Interval.periodWithChargeDay( 1, Unit.WEEK, Weekday.MONDAY ) )
.withPeriodOfValidity( Interval.period( 2, Unit.YEAR ) )
.withStartDate( new Date( 1400575533 ) )
);

pm.subscriptions.fromOffer("pay_5e078197cde8a39e4908f8aa","offer_b33253c73ae0dae84ff4")
.withClient( "client_81c8ab98a8ac5d69f749" )
.withAmount( 3000 )
.withCurrency( "EUR")
.withInterval("1 week,monday")
.withName( "Example Subscription" )
.withPeriodOfValidity( "2 YEAR" )
.withStartDate( new Date(1400575533))
.create().then( function(subscription) {
    console.log("created subscription:" + subscription.id);
}, function(error) {
    console.log("couldnt create subscription:" + error);
});

subscription_service = paymill_context.get_subscription_service();
subscription_with_offer_and_different_values = subscription_service.create_with_offer_id(
    payment_id='pay_5e078197cde8a39e4908f8aa',
    offer_id='offer_b33253c73ae0dae84ff4',
    name='Example Subscription',
    period_of_validity='2 YEAR',
    start_at=1400575533
);

$subscription = new Paymill\Models\Request\Subscription();
$subscription->setClient('client_81c8ab98a8ac5d69f749')
             ->setOffer('offer_40237e20a7d5a231d99b');
             ->setAmount(3000);
             ->setPayment('pay_5e078197cde8a39e4908f8aa');
             ->setCurrency('EUR');
             ->setInterval('1 week,monday');
             ->setName('Example Subscription');
             ->setPeriodOfValidity('2 YEAR');
             ->setStartAt('1400575533');

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

SubscriptionService subscriptionService = paymillContext.SubscriptionService;

subscriptionService.CreateAsync( Subscription.Create(
    "pay_95ba26ba2c613ebb0ca8",
    "offer_40237e20a7d5a231d99b" )
.WithAmount( 3000 )
.WithCurrency( "EUR" )
.WithInterval( Interval.periodWithChargeDay( 1, Interval.TypeUnit.WEEK, Interval.Weekday.MONDAY ) )
.WithPeriodOfValidity( Interval.period( 2, Interval.TypeUnit.YEAR ) )
.withStartDate( DateTime.Now.AddDays(5) )
);

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
charged. Format: number DAY | WEEK | MONTH | YEAR [, WEEKDAY] Example: 2 DAYS, MONDAY ( is required if no offer id is given)

name: string / null
name of the subscription (optional)

period_of_validity: string / null
limit the validity of the subscription, format: integer MONTH | YEAR | WEEK | DAY (optional)

start_at: integer / 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

Request

curl https://api.paymill.com/v2.1/subscriptions/sub_dc180b755d10da324864 \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Subscription.find("sub_dc180b755d10da324864")

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

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

subscription_service = paymill_context.get_subscription_service();
subscription_details = subscription_service.detail(subscription_without_offer)

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

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

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

Response

{
    "data" :{
            "id":"sub_dc180b755d10da324864",
            "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 https://api.paymill.com/v2.1/subscriptions/sub_dea86e5c65b2087202e3 \
  -u <YOUR_PRIVATE_KEY>: \
  -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
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
subscription.payment = 'pay_95ba26ba2c613ebb0ca8'
subscription.currency = 'USD'
subscription.interval = '1 month,friday'
subscription.name = 'Changed Subscription'
subscription.trial_end = false
subscription.update

# for limit / unlimit use
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
subscription.unlimit
subscription.limit('12 MONTH')

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
Subscription subscription = subscriptionService.get( "sub_dea86e5c65b2087202e3" );
subscription.setName( "Changed Subscription" );
subscriptionService.update( subscription );

pm.subscriptions.detail("sub_dea86e5c65b2087202e3").then(function(subscription) {
    subscription.name = "Changed Subscription";
    return pm.transactions.update(subscription);
}).then(function(updatedSubscription) {
    console.log("updated subscription name:" + updatedSubscription.name);
}, function(error) {
    console.log("couldnt update the subscription:" + error);
});

subscription_service = paymill_context.get_subscription_service();
subscription_without_offer.name = 'Updated Subscription';
subscription_service.update(subscription_without_offer);

$subscription = new Paymill\Models\Request\Subscription();
$subscription->setId('sub_dea86e5c65b2087202e3');
             ->setClient('client_81c8ab98a8ac5d69f749')
             ->setOffer('offer_40237e20a7d5a231d99b');
             ->setAmount(3000);
             ->setPayment('pay_95ba26ba2c613ebb0ca8');
             ->setCurrency('USD');
             ->setInterval('1 month,friday');
             ->setName('Changed Subscription');
             ->setPeriodOfValidity('14 MONTH');
             ->setTrialEnd(false);

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

SubscriptionService subscriptionService = paymillContext.SubscriptionService;

Subscription subscription = subscriptionService.GetAsync( "sub_dea86e5c65b2087202e3" ).Result;

subscription.Name = "Changed Subscription" ;
subscription.Offer = null; // Do not update Offer
subscription.Currency = null;// Do not update Currency
subscription.Interval = null;// Do not update Interval

Subscription updatedSubscription = subscriptionService.UpdateAsync(subscription).Result;

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"
}

Amount

Request

curl https://api.paymill.com/v2.1/subscriptions/sub_dea86e5c65b2087202e3 \
  -u <YOUR_PRIVATE_KEY>: \
  -d "amount=1234" \
  -d "amount_change_type=0" \
  -X PUT
#amount temporary:
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
subscription.update_amount_once(1234)

#amount permanently:
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
subscription.update_amount_permanently(1234)

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
subscriptionService.changeAmountTemporary( "sub_dea86e5c65b2087202e3" , 1234 );

pm.subscriptions.detail("sub_dea86e5c65b2087202e3").then(function(subscription) {
    return pm.transactions.changeAmountTemporary(subscription, 1234);
}).then(function(updatedSubscription) {
    console.log("updated subscription amount:" + updatedSubscription.amount);
}, function(error) {
    console.log("couldnt update the subscription:" + error);
});

subscription_service = paymill_context.get_subscription_service();
subscription_without_offer.amount = 1234;
subscription_service.update_with_amount(subscription_without_offer, amount_change_type=1);

$subscription = new Paymill\Models\Request\Subscription();
$subscription->setId('sub_dea86e5c65b2087202e3');
             ->setAmount(1234);
             ->setAmountChangeType(0);

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

SubscriptionService subscriptionService = paymillContext.SubscriptionService;

Subscription updatedSubscription = subscriptionService.ChangeAmountTemporaryAsync( "sub_dea86e5c65b2087202e3" , 1234 ).Result;

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"
}

Offer

Request

curl https://api.paymill.com/v2.1/subscriptions/sub_dea86e5c65b2087202e3 \
  -u <YOUR_PRIVATE_KEY>: \
  -d "offer=offer_d7e9813a25e89c5b78bd" \
  -d "offer_change_type=2" \
  -X PUT
#offer with no refund and unchanged capture date:
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
offer = Offer.create(name: 'Foo', amount: 4990, currency: 'EUR', interval: '2 WEEK')
subscription.update_offer_without_changes(offer)

#offer with refund and unchanged capture date:
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
offer = Offer.create(name: 'Foo', amount: 4990, currency: 'EUR', interval: '2 WEEK')
subscription.update_offer_with_refund(offer)

#offer with refund and capture date:
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
offer = Offer.create(name: 'Foo', amount: 4990, currency: 'EUR', interval: '2 WEEK')
subscription.update_offer_with_refund_and_capture_date(offer)

Offer offer = paymillContext.getOfferService().get( "offer_d7e9813a25e89c5b78bd" );
SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
Subscription subscription = subscriptionService.get( "sub_dea86e5c65b2087202e3" );
subscriptionService.changeOfferChangeCaptureDateAndRefund( subscription, offer );

pm.subscriptions.detail("sub_dea86e5c65b2087202e3").then(function(subscription) {
    return pm.transactions.changeOfferChangeCaptureDateAndRefund(subscription, "offer_d7e9813a25e89c5b78bd");
}).then(function(updatedSubscription) {
    console.log("updated subscription offer:" + updatedSubscription.offer.id);
}, function(error) {
    console.log("couldnt update the subscription:" + error);
});

subscription_service = paymill_context.get_subscription_service();
subscription_with_an_offer.offer_id='offer_40237e20a7d5a231d99b';
subscription_service.update_with_offer_id(
    subscription_with_an_offer,
    offer_change_type=2
);

$subscription = new Paymill\Models\Request\Subscription();
$subscription->setId('sub_dea86e5c65b2087202e3');
             ->setOffer('offer_d7e9813a25e89c5b78bd');
             ->setOfferChangeType(2);

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

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

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

Subscription updatedSubscription = subscriptionService.ChangeOfferChangeCaptureDateAndRefundAsync( subscription, offer ).Result;

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"
}

Pause

Request

curl https://api.paymill.com/v2.1/subscriptions/sub_dea86e5c65b2087202e3 \
  -u <YOUR_PRIVATE_KEY>: \
  -d "pause=true" \
  -X PUT
#pause:
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
subscription.pause

#play:
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
subscription.play

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
subscriptionService.pause( "sub_dea86e5c65b2087202e3" );

pm.subscriptions.detail("sub_dea86e5c65b2087202e3").then(function(subscription) {
    return pm.transactions.pause(subscription);
}).then(function(updatedSubscription) {
    console.log("updated subscription status:" + updatedSubscription.status);
}, function(error) {
    console.log("couldnt update the subscription:" + error);
});

# pause
subscription_service = paymill_context.get_subscription_service();
subscription_service.pause(subscription_without_offer);
# unpause
subscription_service = paymill_context.get_subscription_service();
subscription_service.unpause(subscription_without_offer);

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

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

SubscriptionService subscriptionService = paymillContext.SubscriptionService;

Subscription updatedSubscription = subscriptionService.PauseAsync( "sub_dea86e5c65b2087202e3" ).Result;

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=), 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: integer / 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: integer
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 https://api.paymill.com/v2.1/subscriptions/sub_dea86e5c65b2087202e3 \
  -u <YOUR_PRIVATE_KEY>: \
  -d "remove=false" \
  -X DELETE
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
subscription.cancel()

SubscriptionService subscriptionService = paymillContext.getSubscriptionService();
subscriptionService.cancel( "sub_dea86e5c65b2087202e3" );

pm.subscriptions.cancel("sub_d68bcdc8656a7932eb44").then(function(subscription) {
    console.log("canceled subscription :" + subscription.status);
}, function(error) {
    console.log("couldnt cancel subscription:" + error);
});

subscription_service = paymill_context.get_subscription_service();
subscription_service.cancel(subscription_without_offer);

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

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

SubscriptionService subscriptionService = paymillContext.SubscriptionService;

Subscription updatedSubscription = subscriptionService.CancelAsync( "sub_dea86e5c65b2087202e3" ).Result;

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"
}

Delete

Request

curl https://api.paymill.com/v2.1/subscriptions/sub_d68bcdc8656a7932eb44 \
  -u <YOUR_PRIVATE_KEY>: \
  -d "remove=true" \
  -X DELETE
subscription = Paymill::Subscription.find('sub_dea86e5c65b2087202e3')
subscription.remove()

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

pm.subscriptions.delete("sub_d68bcdc8656a7932eb44").then(function(subscription) {
    console.log("deleted subscription :" + subscription.status);
}, function(error) {
    console.log("couldnt delete subscription:" + error);
});

subscription_service = paymill_context.get_subscription_service();
subscription_service.remove(subscription_without_offer);

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

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

SubscriptionService subscriptionService = paymillContext.SubscriptionService;

subscriptionService.DeleteAsync( "sub_dea86e5c65b2087202e3" ).Wait();

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

Request

curl https://api.paymill.com/v2.1/subscriptions \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Subscription.all()

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

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);
});

subscription_service = paymill_context.get_subscription_service();
subscription_list = subscription_service.list();

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

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

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

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

Export Subscriptions List

Request

curl https://api.paymill.com/v2.1/subscriptions \
  -u <YOUR_PRIVATE_KEY>: \
  -H "Accept: text/csv"
# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

Response

"id";"livemode";"amount";"temp_amount";"currency";"name";"interval";"trial_start";"trial_end";"period_of_validity";"end_of_period";"next_capture_at";"created_at";"updated_at";"canceled_at";"app_id";"is_canceled";"is_deleted";"status";"offer_id";"client_id";"payment_id"
"sub_c84aadd0c1c7529158ee";"";"499";"";"EUR";"Example Subscription";"3 WEEK";"1401983620";"1404575620";"";"";"";"1342427064";"1342427064";"1402640050";"";"";"";"active";"offer_1a5d80dc75db9b5c0c64";"client_33c8f8c13d759d00b144";"pay_2311e5a076ab0b9c2cdb0399"

This function returns CSV separated by semicolons, encapsulated by double quotes, with a list of subscriptions. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • created_at
  • updated_at

Available filters:

  • offer
  • currency
  • created_at
  • canceled_at
  • updated_at

Webhooks

Webhooks details

  • 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 Merchant Centre.

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

Events

Available events

  • chargeback.executed: returns a transaction-object with state set to chargeback
  • transaction.created: returns a transaction-object
  • transaction.pending: returns a transaction object when a transaction was created but is still pending
  • 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
    }
 }

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

Example URL webhook

{
     "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: boolean
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 / null
App (ID) that created this webhook or null if created by yourself

Create new URL Webhook

Request

curl https://api.paymill.com/v2.1/webhooks \
  -u <YOUR_PRIVATE_KEY>: \
  -d "url=<your-webhook-url>" \
  -d "event_types[]=transaction.succeeded" \
  -d "event_types[]=transaction.failed"
Paymill::Webhook.create(
    url: 'http://example.com',
    event_types: ['transaction.succeeded', 'transaction.failed']
)

WebhookService webhookService = paymillContext.getWebhookService();
EventType[] eventTypes = new EventType[] {
    EventType.TRANSACTION_SUCCEEDED,
    EventType.TRANSACTION_FAILED
};
Webhook webhook = webhookService.createUrlWebhook(
    "",
    eventTypes
);

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

webhook_service = paymill_context.get_webhook_service();
url_webhook = webhook_service.create_url(
    url='',
    event_types=['transaction.succeeded', 'transaction.failed'],
    active=True
)

$webhook = new Paymill\Models\Request\Webhook();
$webhook->setUrl('')
        ->setEventTypes(array(
            'transaction.succeeded',
            'transaction.failed'
        ));

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

WebhookService webhookService = paymillContext.WebhookService;
EventType[] eventTypes = new EventType[] {
    EventType.TRANSACTION_SUCCEEDED,
    EventType.TRANSACTION_FAILED
}.Result;
Webhook webhook = webhookService.CreateUrlWebhookAsync(
    "",
    eventTypes
).Result;

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: boolean
can be used to create an inactive webhook in the beginning

Create new E-Mail Webhook

Request

curl https://api.paymill.com/v2.1/webhooks \
  -u <YOUR_PRIVATE_KEY>: \
  -d "email=<your-webhook-email>" \
  -d "event_types[]=subscription.succeeded" \
  -d "event_types[]=subscription.failed"
Paymill::Webhook.create(
    email: 'webhook@example.com',
    event_types: ['transaction.succeeded', 'transaction.failed'],
    active: false
)

WebhookService webhookService = paymillContext.getWebhookService();
EventType[] eventTypes = new EventType[] {
    EventType.TRANSACTION_SUCCEEDED,
    EventType.TRANSACTION_FAILED
};
Webhook webhook = webhookService.createEmailWebhook(
    "",
    eventTypes
);

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

webhook_service = paymill_context.get_webhook_service();
email_webhook = webhook_service.create_email(
    email='lovely-webhook@example.com',
    event_types=['transaction.succeeded', 'transaction.failed'],
    active=True
)

$webhook = new Paymill\Models\Request\Webhook();
$webhook->setEmail('')
        ->setEventTypes(array(
            'transaction.succeeded',
            'transaction.failed'
        ));

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

WebhookService webhookService = paymillContext.WebhookService;
EventType[] eventTypes = new EventType[] {
    EventType.TRANSACTION_SUCCEEDED,
    EventType.TRANSACTION_FAILED
};
Webhook webhook = webhookService.CreateEmailWebhookAsync(
    "",
    eventTypes
).Result;

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"
}

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

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: boolean
can be used to create an inactive webhook in the beginning

Webhook details

Request

curl https://api.paymill.com/v2.1/webhooks/hook_40237e20a7d5a231d99b \
  -u <YOUR_PRIVATE_KEY>:
Paymill::Webhook.find('hook_40237e20a7d5a231d99b')

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

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

webhook_service = paymill_context.get_webhook_service();
webhook_details = webhook_service.detail(email_webhook)

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

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

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

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.

Attributes

id: string
Unique identifier for the webhook

Update Webhook

Request

curl https://api.paymill.com/v2.1/webhooks/hook_40237e20a7d5a231d99b \
   -u <YOUR_PRIVATE_KEY>: \
   -d "url=<new-webhook-url>" \
   -X PUT
webhook = Paymill::Webhook.find(active_webhook_id)
webhook.email = 'mail@example.com'
webhook.update()

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

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

webhook_service = paymill_context.get_webhook_service();
email_webhook.email = 'updated-lovely-webhook@example.com'
webhook_service.update(email_webhook);

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

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

WebhookService webhookService = paymillContext.WebhookService;
Webhook webhook = webhookService.GetAsync("hook_40237e20a7d5a231d99b").Result;
webhook.Email = "test1@mail.com";
webhookService.UpdateAsync( webhook ).Wait();

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: boolean activate / deactivate webhook

List Webhooks

Request

curl https://api.paymill.com/v2.1/webhooks/ \
  -u <YOUR_PRIVATE_KEY>:
The partial "snippets/ruby/samples/webhooks/list_webhooks.rb" was not found, as such it will not be rendered.
WebhookService webhookService = paymillContext.getWebhookService();
PaymillList webhooks = webhookService.list();

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);
});

webhook_service = paymill_context.get_webhook_service();
webhooks_list = webhook_service.list();

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

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

WebhookService webhookService = paymillContext.WebhookService;
PaymillList webhooks = webhookService.ListAsync();

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 subscriptions. 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)>

Export Webhooks List

Request

curl https://api.paymill.com/v2.1/webhooks \
  -u <YOUR_PRIVATE_KEY>: \
  -H "Accept: text/csv"
# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

# Not implemented yet

/* Not implemented yet */

/* Not implemented yet */

Response

"id";"livemode";"created_at";"updated_at";"active";"app_id";"version";"url";"event_types"
"hook_f0f84bc71b86f16fa1f5";"";"1342427064";"1342427064";"1";"";"2.1";;"refund.succeeded"

This function returns CSV separated by semicolons, encapsulated by double quotes, with a list of webhooks. In which order this list is returned depends on the optional parameter order. The following parameters can be used:

  • created_at
  • email
  • updated_at
  • url

Available filters:

  • email
  • url
  • created_at

Internal Objects

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

Address Object

An address object belongs to exactly one transaction and can represent either its shipping address or billing address. Note that state and postal_code are mandatory for PayPal transactions in certain countries, please consult PayPal documentation for more details.

Example

{
    "name": "Max Mustermann",
    "street_address": "Musterstr. 1",
    "street_address_addition": "",
    "city": "Munich",
    "state": "Bavaria",
    "postal_code": "80333",
    "country": "DE",
    "phone": "+4989123456"
}

Attributes

name: string Name of recipient, max. 128 characters

street_address: string
Street address (incl. street number), max. 100 characters

street_address_addition: string
Addition to street address (e.g. building, floor, or c/o), max. 100 characters

city: string
City, max. 40 characters

state: string
State or province, max. 40 characters

postal_code: string
Country-specific postal code, max. 20 characters

country: string
2-letter country code according to ISO 3166-1 alpha-2

phone: string
Contact phone number, max. 20 characters

Fee object

Example

{
    "type": "application",
    "application": "app_1d70acbf80c8c35ce83680715c06be0d15c06be0d",
    "payment": "pay_917018675b21ca03c4fb",
    "amount": 420,
    "currency": "EUR",
    "billed_at": null
}

Attributes

url 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

Example

{
    "invoice_nr": "1293724",
    "netto": 12399,
    "brutto": 14755,
    "status": "sent",
    "period_from": 1349946151,
    "period_until": 1352538151,
    "currency": "EUR",
    "vat_rate": 19,
    "billing_date": 1353142951,
    "invoice_type": "paymill",
    "last_reminder_date": null
}

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

Example

{
    "identifier_key": "mer_123456789",
    "email": "mail@example.com",
    "locale": "de_DE",
    "country": "DEU",
    "currencies": ["EUR", "GPB"],
    "methods": ["visa", "mastercard"]
}

Attributes

identifier_key string
Unique identifier of this merchant

email string
email address

locale string
culture setting

county string / 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
List of activated card brands

Payment method object

Example

{
    "type": "visa",
    "currency": "EUR",
    "acquirer": "wirecard"
}

Attributes

type string
Card brand (e.g. visa, mastercard, amex, elv, sepa etc.)

currency string
ISO 4217 formatted currency code

acquier string
Acquiring bank enum(wirecard, acceptance, none)

Shopping cart item Object

Example

{
    "name": "Sample Product",
    "description": "Amazing product used as an example",
    "item_number": "PRD12345",
    "url": "https://www.example.com/shop/products/12345",
    "amount": 1000,
    "quantity": 3
}

Attributes

name: string
Item name, max. 127 characters

description: string
Additional description, max. 127 characters

amount: integer (> 0)
Price for a single item, including tax, can also be negative to act as a discount

quantity: integer (> 0)
Quantity of this item

item_number: string
Item number or other identifier (SKU/EAN/…), max. 127 characters

url: string
URL of the item in your store, max. 2000 characters