Peakium API


The Peakium API is build on REST principles with resource-oriented URL's. The API is using HTTP status codes for errors. All responses will be returned in JSON format.

API Endpoints

Authentication

Authentication to the API is granted by using the test or live API key in your Peakium account. The API will request authentication via HTTP Basic Auth. For the username, you will use the API key, and for the password you do not need to enter anything.

API keys can be found and rolled, when logged into your Peakium account. Please keep your API keys secure as they allow for many irreversible actions.

Authentication are mandatory for all requests to the API.

Example on authenticating an API request through curl:

$ curl https://secure.peakium.com/api/v1/customers \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

SSL

All requests are required to be done through HTTPS. Requests over plain HTTP will be rejected.

Errors

Peakium uses HTTP status codes to indicate errors (or success). Codes in range 2xx indicates success, codes in 4xx range indicates a client side error (e.g. a missing or invalid parameter), and codes in 5xx range indicates an error in Peakium's system.

HTTP status code errors

Error Description
200 OK The request was handled and returned correctly
400 Bad Request Missing a required parameter, or using an invalid parameter
401 Unauthorized No valid API key used
404 Not Found A resource was not found
500 Internal Server Error Something went wrong in Peakium's system

Error return

The returning JSON on errors will often include the following attributes:

Name Description
message A human-readable message giving information about the error.

Versioning

Currently there is no versioning of the API. All users will be notified when backwards-incompatible changes are to be introduced.

Expanding objects

If an object contains the ID of another object, you can expand this object by using the expand attribute. As an example, you might want to view the customer for a subscription, thus the API call will be:

$ curl https://secure.peakium.com/api/v1/subscription/50aaeccb73dd310010 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d "expand[]=customer"

Identify your app

The Peakium API app will record logs of your requests. If you wish to more easily identify your apps, you can add a User-Agent header to the request. Example:

User-Agent: Dan's Integration (dan@example.com)

Help us

We always love to hear from you if you have any ideas of how to make the API better. You can contact us directly at beta@peakium.com with your suggestions. Also, feel free to fork these docs and send a pull request with improvements!

Need an account?

We're currently in closed beta, but you can signup for an invite at http://peakium.com/

Customer


The ID of a customer object is the same as the ID you have given through your application.

The customer object is read only.

The customer object

Attributes

Name Type Description
id string
object string Is "customer".
created integer
balances list A list of the customer's balances separated into currencies.
metadata object

Example

{
    "id": "cu4321",
    "object": "customer",
    "created": 1375217068,
    "balances": {
        "USD": 5612
    },
    "metadata": {}
}

List all customers

Returns a list of all customers.

Arguments

Name Required Description
count optional
offset optional

Example request

curl https://secure.peakium.com/api/v1/customers/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "id": "cu4321",
            "object": "customer",
            "created": 1375217068,
            "balances": {
                "USD": 5612
            },
            "metadata": {}
        },
        {...}
    ]
}

Create or update customer

Arguments

Name Required/Optional Description
id required The unique customer ID.
metadata optional An array.

Example request create

$ curl https://secure.peakium.com/api/v1/customers/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d id="UNIQUE_ID"

Example request update

$ curl https://secure.peakium.com/api/v1/customers/UNIQUE_ID/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d metadata[name]="Customer Name"

Example response

Will respond with 200 OK status, and the full customer object if valid, or fail with failure HTTP status code.

Event


When an event object is created, subsequent event webhooks are created based on the webhook endpoints registered at the moment of the creation.

The event object has a method to be validated for added security.

An event webhook will be tried to be delivered each hour until delivered, or until 24 tries. The event webhook(s) can, at any time, be requested through the API to be resend to webhook endpoints.

The event object

Attributes

Name Type Description
id string
object string Is "event".
event string The event type.
created integer
data object Referencing data. E.g. customer, invoice or subscription.

Example

{
    "id": "ev_TlSEvdkrRAg4aD",
    "object": "event",
    "event": "subscription.created",
    "created": 1375217068,
    "data": {
        "object": {
            "token": "50aaeccb73dd310010",
            "object": "subscription",
            "created": 1375217068,
            "display_name": "Plus Plan",
            "plan": {
                "period_amount": 1,
                "period_type": "M",
                "amount": 7200,
                "currency": "USD",
                "discount": 0.0,
                "item_id": 101
            },
            "cycle_number": 1,
            "period_start": 1375217068,
            "period_end": 1375217068,
            "next_charge": 1375217068,
            "status": "active",
            "customer": {
                "id": "cu4321",
                "object": "customer",
            }
        }
    }
}

Event types

Event Description
customer.created A customer has been created
customer.updated A customer has been updated
invoice.created An invoice has been created. You should note that items might change before invoice.locked.
invoice.locked An invoice has been locked for payment. There will be no further changes to the invoice.
invoice.paid An invoice has been paid.
invoice.payment_failed An invoice could not be paid.
payment_session.started Payment session has been started.
subscription.cancelled A subscription has been cancelled.
subscription.created A subscription has been created.
subscription.updated A subscription has been updated.

List all events

Returns a list of all events.

Arguments

Name Required Description
count optional
offset optional
customer optional
invoice optional
subscription optional Requires the customer argument to be defined also.

Example request

$ curl https://secure.peakium.com/api/v1/events/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "id": "ev_TlSEvdkrRAg4aD",
            "object": "event",
            "event": "subscription.created",
            "created": 1375217068,
            "data": {
                "object": {
                    "token": "50aaeccb73dd310010",
                    "object": "subscription",
                    "created": 1375217068,
                    "display_name": "Plus Plan",
                    "plan": {
                        "period_amount": 1,
                        "period_type": "M",
                        "amount": 7200,
                        "currency": "USD",
                        "discount": 0.0,
                        "item_id": 101
                    },
                    "cycle_number": 1,
                    "period_start": 1375217068,
                    "period_end": 1375217068,
                    "next_charge": 1375217068,
                    "status": "active",
                    "customer": {
                        "id": "cu4321",
                        "object": "customer"
                    }
                }
            }
        },
        {...}
    ]
}

Validate an event

To make sure that a request is not forged, you can validate the authenticity of an incoming event webhook. Send the full retrieved JSON event in the body as a POST request.

Example request

$ curl https://secure.peakium.com/api/v1/events/ev_TlSEvdkrRAg4aD/validate/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d '{"id":"ev_TlSEvdkrRAg4aD","object":"event","event":"subscription.created","created":1375217068,"data":{"token":"50aaeccb73dd310010","object":"subscription","created":1375217068,"display_name":"PlusPlan","plan":{"period_amount":1,"period_type":"M","amount":7200,"currency":"USD","discount":0.0,"item_id":101},"cycle_number":1,"period_start":1375217068,"period_end":1375217068,"next_charge":1375217068,"status":"active","customer":{"id":"cu4321","object":"customer"}}}'

Example response

Will respond with 200 OK status, and the full event object if valid, or fail with failure HTTP status code..

Resending an event

In certain cases you might want to resend events right away. The resend request can be directed to a specific event webhook endpoint, or to all the event webhooks existing for the event at once.

Arguments

Name Required Description
force optional Boolean representing if the delivery should be forced or not. A forced delivery results in the event being send even if the event webhook is in a time lock.
url optional The URL for a specific webhook endpoint. If the webhook endpoint doesn't exist, the API will return 400 Bad Request.

Example request

$ curl https://secure.peakium.com/api/v1/events/ev_TlSEvdkrRAg4aD/send/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d force=true \
    -d url="http://example.com/webhook_endpoint/"

Example response

Will respond with 200 OK status, and the full event object if valid, or fail with failure HTTP status code.

Event webhook


An event webhook object will be created whenever an event is created. The event webhook is making sure that a specific webhook endpoint receives the event.

The event webhook object is read-only.

The event webhook object

Attributes

Name Type Description
object string Is "event_webhook"
created integer
number_of_attempted_deliveries integer
last_delivery_attempt integer The timestamp for the last delivery attempt
delivered boolean
timestamp_delivered integer
url string
event object The event object.

Example

{
    "object": "event_webhook",
    "number_of_attempted_deliveries": 1,
    "last_delivery_attempt": 1375217068,
    "delivered": true,
    "delivered_timestamp": 1375217068,
    "url": "http://example.com/webhook_endpoint/",
    "event": {
        "id": "ev_TlSEvdkrRAg4aD",
        "object": "event",
        "event": "subscription.created",
        "created": 1375217068,
        "subscription": {
            "id": "50aaeccb73dd310010",
            "object": "subscription"
        },
    },
}

List all event webhooks

Returns a list of all event webhooks.

Arguments

Name Required Description
count optional
offset optional
event optional
url optional

Example request

$ curl https://secure.peakium.com/api/v1/event_webhooks/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "object": "event_webhook",
            "number_of_attempted_deliveries": 1,
            "last_delivery_attempt": 1375217068,
            "delivered": true,
            "delivered_timestamp": 1375217068,
            "url": "http://example.com/webhook_endpoint/",
            "event": {
                "id": "ev_TlSEvdkrRAg4aD",
                "object": "event",
                "event": "subscription.created",
                "created": 1375217068,
                "subscription": {
                    "id": "50aaeccb73dd310010",
                    "object": "subscription"
                },
            },
        },
        {...}
    ]
}

Gateway


The gateway object(s) is the gateway(s) that you can use to do payments. The gateway(s) is listed in your Peakium account.

The gateway object

Attributes

Name Type Description
id string
object string Is "gateway".
created integer
name string The reference name for your gateway.
active boolean
default boolean
necessary_gateway_setting_values object An array of values that is necessary to set at the gateway.
module object The gateway module.
settings array

Example

{
    "id": "gw_TlTNIsHSf5lh85",
    "object": "gateway",
    "created": 1375217068,
    "name": "Paypal",
    "display_name": "Paypal",
    "active": true,
    "default": false,
    "necessary_gateway_setting_values": {},
    "module": {
        "object": "gateway_module",
        "name": "Paypal_Payments_Standard",
        "required_fields": [
            "paypal_email"
        ],
        "necessary_gateway_settings": [
            "instant_payment_notification_url"
        ],
        "required_field_parameters": {
            "paypal_email": {
                "description": "The e-mail of the Paypal account."
            }
        }
    },
    "settings": {
        "paypal_email": "paypal@example.com"
    }
}

List all gateway

Returns a list of all available gateways.

Arguments

Name Required Description
count optional
offset optional

Example request

$ curl https://secure.peakium.com/api/v1/gateways/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "id": "gw_TlTNIsHSf5lh85",
            "object": "gateway",
            "created": 1375217068,
            "name": "Paypal",
            "display_name": "Paypal",
            "active": true,
            "default": false,
            "necessary_gateway_setting_values": {},
            "module": {
                "object": "gateway_module",
                "name": "Paypal_Payments_Standard",
                "required_fields": [
                    "paypal_email"
                ],
                "necessary_gateway_settings": [
                    "instant_payment_notification_url"
                ],
                "required_field_parameters": {
                    "paypal_email": {
                        "description": "The e-mail of the Paypal account."
                    }
                }
            },
            "settings": {
                "paypal_email": "paypal@example.com"
            }
        },
        {...}
    ]
}

Set a gateway as the default gateway

A specific gateway can be set as the default gateway to use. Any previous default gateway will be unset as the default gateway.

Example request

$ curl https://secure.peakium.com/api/v1/gateways/gw_TlTNIsHSf5lh85/default/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -X POST

Example response

Will respond with 200 OK status, and the full gateway object if valid, or fail with HTTP status codes.

Create or update a gateway

A gateway can be created and/or updated over the API.

Arguments

Name Required/Optional Description
name required The gateway reference name.
module required The gateway module name.
settings required An array of settings for the gateway.

Example request create

$ curl https://secure.peakium.com/api/v1/gateways/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d name="Paypal" \
    -d display_name="Paypal" \
    -d module="Paypal_Payments_Standard" \
    -d settings["paypal_email"]="paypal@example.com"

Example request update

$ curl https://secure.peakium.com/api/v1/gateways/gw_TlTNIsHSf5lh85/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d name="Paypal" \
    -d display_name="Paypal" \
    -d module="Paypal_Payments_Standard" \
    -d settings["paypal_email"]="paypal@example.com"

Example response

Will respond with 200 OK status, and the full gateway object if valid, or fail with failure HTTP status code.

Delete a gateway

Only gateways that has no payment data can be deleted.

Example request

$ curl https://secure.peakium.com/api/v1/gateways/gw_TlTNIsHSf5lh85/ \ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -X DELETE

Example response

{
    "id": "gw_TlTNIsHSf5lh85",
    "deleted": true
}

Invoice


The invoice object presents invoices that has been created in relation to a subscription or customer in your account.

The invoice object

Attributes

Name Type Description
id string
object string Is "invoice".
created integer
due integer When the invoice is to be paid the latest.
locked boolean
timestamp_locked integer
paid boolean
timestamp_paid integer
retracted boolean
timestamp_retracted integer
type string Describes if the invoice is a recurring event, or is a user based action.
calculated_total array An array containing the currency and amount calculated to be paid in the invoice. The invoice might change during it's lifetime, so it is a current view of the total for the invoice.
calculated_total->currency string
calculated_total->amount integer
attempt_automatic_charge boolean If an invoice will be automatically charged, or requires action from the customer.
items array An array containing a list of invoice item objects.
customer object
charge object
metadata object

Example

{
    "id": "in_TlQFJ1ZvXfuX2g",
    "object": "invoice",
    "created": 1375217068,
    "due": 1375217068,
    "locked": true,
    "timestamp_locked": 1375217068,
    "paid": true,
    "timestamp_paid": 1375217068,
    "retracted": false,
    "timestamp_retracted": null,
    "type": "single",
    "calculated_total": {
        "currency": "USD",
        "amount": 7200
    },
    "attempt_automatic_charge": true,
    "items": [
        {
            "object": "invoice_item",
            "type": "debit",
            "sequence": 1,
            "description": "Plus Plan",
            "item_id": 101,
            "unit_amount": 7200,
            "currency": "USD",
            "quantity": 1,
            "date_range_start": 1375217068,
            "date_range_end": 1375217068,
            "discount": 0.0,
            "total_amount": 7200,
            "reference": {
                "id": "50aaeccb73dd310010",
                "object": "subscription"
            }
        }
    ],
    "customer": {
        "id": "cu4321",
        "object": "customer"
    },
    "charge": {
        "object": "charge",
        "amount": 7200,
        "currency": "USD",
        "paid": true,
        "timestamp_paid": 1375217068,
        "status": "completed",
        "refunded": false,
        "refunds": {
            "object": "list",
            "count": 0,
            "data": []
        }
    },
    "metadata": {}
}

List all invoices

Returns a list of all invoices.

Arguments

Name Required Description
count optional
offset optional
customer optional
overdue optional Boolean presenting if only overdue invoices should be returned
item_id optional Return invoices containing invoice items with certain item id

Example request

$ curl https://secure.peakium.com/api/v1/invoices/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "id": "in_TlQFJ1ZvXfuX2g",
            "object": "invoice",
            "created": 1375217068,
            "due": 1375217068,
            "locked": true,
            "timestamp_locked": 1375217068,
            "paid": true,
            "timestamp_paid": 1375217068,
            "retracted": false,
            "timestamp_retracted": null,
            "type": "single",
            "calculated_total": {
                "currency": "USD",
                "amount": 7200
            },
            "attempt_automatic_charge": true,
            "items": [
                {
                    "object": "invoice_item",
                    "type": "debit",
                    "sequence": 1,
                    "description": "Plus Plan",
                    "item_id": 101,
                    "unit_amount": 7200,
                    "currency": "USD",
                    "quantity": 1,
                    "date_range_start": 1375217068,
                    "date_range_end": 1375217068,
                    "discount": 0.0,
                    "total_amount": 7200,
                    "reference": {
                        "id": "50aaeccb73dd310010",
                        "object": "subscription"
                    }
                }
            ],
            "customer": {
                "id": "cu4321",
                "object": "customer"
            },
            "charge": {
                "object": "charge",
                "amount": 7200,
                "currency": "USD",
                "paid": true,
                "timestamp_paid": 1375217068,
                "status": "completed",
                "refunded": false,
                "refunds": {
                    "object": "list",
                    "count": 0,
                    "data": []
                }
            },
            "metadata": {}
        },
        {...}
    ]
}

Attempt payment of an invoice

It is possible with certain invoices to attempt a payment at the present time. You can request an invoice to be paid through the API. Payments are only possible for API type gateways, and not external type gateways.

Example request

$ curl https://secure.peakium.com/api/v1/invoices/in_TlQFJ1ZvXfuX2g/pay/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -x POST

Example response

Will respond with 200 OK status, and the full invoice object if payment could go through, or fail with HTTP status codes.

Update an invoice

Only metadata can be updated.

Arguments

Name Required/Optional Description
metadata required An array.

Example request update

$ curl https://secure.peakium.com/api/v1/invoice/in_TlQFJ1ZvXfuX2g/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d metadata[order_number]="#0012"

Example response

Will respond with 200 OK status, and the full invoice object if valid, or fail with failure HTTP status code.

Payment Session


Payment sessions are created when customers initiate a payment process that requires an external gateway (such as Paypal Payments Standard).

The payment session object

Attributes

Name Type Description
id string
object string Will be "webhook"
created integer
handled boolean
timestamp_handled integer
payment_amount string
payment_currency integer
action string Type of action the user has requested
ip string
user_agent string
parameters array
gateway object The gateway object used for the payment session.
customer object Will be populated if a customer is identified.
charge object

Example

{
    "id": "payment_session",
    "object": "payment_session",
    "created": 1375217068,
    "handled": true,
    "timestamp_handled": 1375217068,
    "payment_amount": 7200,
    "payment_currency": "USD",
    "action": "subscription-update",
    "ip": "172.16.254.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.93 Safari/537.36",
    "posted_values": {
        "customer": "cu4321",
        "subscription": "50aaeccb73dd310010",
        "item_description": "Plus Plan",
        "item_id": 101,
        "period_amount": 1,
        "period_type": "month",
        "payment_amount": 7200,
        "payment_currency": "USD",
        "payment_discount": 0.00,
        "return_url_ok": "http://example.org/payment/success/",
        "return_url_error: "http://example.org/payment/error/",
        "publishable_key": "pk_QTBkCKdRworbXYZens4V4LZZs1X00FeM",
        "gateway": "gw_TlTNIsHSf5lh85",
        "integrity_value": "b860f950df56104a9328e44f6b3ce6e30f6db55a"
    },
    "gateway": "gw_TlTNIsHSf5lh85",
    "customer": "cu4321",
    "charge": {
        "object": "charge",
        "amount": 7200,
        "currency": "USD",
        "paid": true,
        "timestamp_paid": 1375217068,
        "status": "completed"
    }
}

List all payment sessions

Returns a list of all payment sessions.

Arguments

Name Required Description
count optional
offset optional

Example request

$ curl https://secure.peakium.com/api/v1/payment_session/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "id": "payment_session",
            "object": "payment_session",
            "created": 1375217068,
            "handled": true,
            "timestamp_handled": 1375217068,
            "payment_amount": 7200,
            "payment_currency": "USD",
            "action": "subscription-update",
            "ip": "172.16.254.1",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.93 Safari/537.36",
            "posted_values": {
                "customer": "cu4321",
                "subscription": "50aaeccb73dd310010",
                "item_description": "Plus Plan",
                "item_id": 101,
                "period_amount": 1,
                "period_type": "month",
                "payment_amount": 7200,
                "payment_currency": "USD",
                "payment_discount": 0.00,
                "return_url_ok": "http://example.org/payment/success/",
                "return_url_error: "http://example.org/payment/error/",
                "publishable_key": "pk_QTBkCKdRworbXYZens4V4LZZs1X00FeM",
                "gateway": "gw_TlTNIsHSf5lh85",
                "integrity_value": "b860f950df56104a9328e44f6b3ce6e30f6db55a"
            },
            "gateway": "gw_TlTNIsHSf5lh85",
            "customer": "cu4321",
            "charge": {
                "object": "charge",
                "amount": 7200,
                "currency": "USD",
                "paid": true,
                "timestamp_paid": 1375217068,
                "status": "completed"
            }
        },
        {...}
    ]
}

Submission Form


The submission form resource is not an actual data resource. It is a helper resource that returns submission forms so your customers can be transferred smoothly to the correct location when necessary.

For security, each form contains a field with a salted integrity hash to secure against modification of the POST values. For your convenience Peakium automatically build these forms through the API with this resource handle.

When user is returned to return_url_ok, either a invoice or payment_session param will be set. When an invoice param is set, it means that the payment has gone through, while payment_session means that the user is currently paying with an external gateway (like bank transfer).

Form for new subscriptions

This call will build a form so customers can create new subscriptions through any gateway you have registered at Peakium.

Arguments

Name Required Description
customer required The reference id for your customer object in your application.
subscription required The reference id for your customer-specific subscription object in your application.
items required A list of items the subscription has
items>item_id required
items>item_description required
items>unit_amount required
items>currency optional
items>quantity optional
items>discount optional
period_amount required Number of days, months or years
period_type required day, month or year
payment_currency required If currency in an item is set this is not needed
return_url_ok required
return_url_error required
pro_rata optional
gateway optional If not defined, the gateway parameter will be set automatically depending on default payment method for your customer, and your default gateway.
submit_button_text optional What text the submit button should contain. Default is "Click here if you are not redirected within 10 seconds".
auto_submit_page optional A boolean value representing if the returning HTML should include the full auto submit page. If false, or undefined, only the form element will be returned.
auto_submit_page_title optional A string for the title to display in the auto submit page. Default is "Redirecting to payment method..."
metadata optional An array of various metadata fields. An example would be: { customer: { user_id: "1234" }, subscription: { extra: "data", invoice: { extra: "data" } } }

Example request

curl https://secure.peakium.com/api/v1/submission_form/create-subscription/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -p customer="cu4321" \
    -p subscription="50aaeccb73dd310010" \
    -p item_description="Plus Plan" \
    -p item_id=101 \
    -p period_amount=1 \
    -p period_type="month" \
    -p payment_amount=7200 \
    -p payment_currency="USD" \
    -p payment_discount=0.0 \
    -p return_url_ok="http://example.org/payment/success/" \
    -p return_url_error="http://example.org/payment/error/" \
    -p auto_submit_page=true

Example response

{
    "html": "<!DOCTYPE html PUBLIC \"-\/\/W3C\/\/DTD XHTML 1.0 Transitional\/\/EN\" \"http:\/\/www.w3.org\/TR\/xhtml1\/DTD\/xhtml1-transitional.dtd\"><html xmlns=\"http:\/\/www.w3.org\/1999\/xhtml\"><head><title>Redirecting to payment method...<\/title><\/head><body><h3>Redirecting to payment method...<\/h3><body onload=\"document.p.submit();\"><form action=\"http:\/\/secure.peakium.com\/update-subscription\/\" method=\"post\" name=\"p\"><input type=\"hidden\" name=\"action\" value=\"create\" \/><input type=\"hidden\" name=\"customer\" value=\"cu4321\" \/><input type=\"hidden\" name=\"subscription\" value=\"50aaeccb73dd310010\" \/><input type=\"hidden\" name=\"item_description\" value=\"Plus Plan\" \/><input type=\"hidden\" name=\"item_id\" value=\"101\" \/><input type=\"hidden\" name=\"period_amount\" value=\"1\" \/><input type=\"hidden\" name=\"period_type\" value=\"month\" \/><input type=\"hidden\" name=\"payment_amount\" value=\"7200\" \/><input type=\"hidden\" name=\"payment_currency\" value=\"USD\" \/><input type=\"hidden\" name=\"payment_discount\" value=\"0\" \/><input type=\"hidden\" name=\"return_url_ok\" value=\"http:\/\/example.org\/payment\/success\/\" \/><input type=\"hidden\" name=\"return_url_error\" value=\"http:\/\/example.org\/payment\/error\/\" \/><input type=\"hidden\" name=\"publishable_key\" value=\"pk_QTBkCKdRworbXYZens4V4LZZs1X00FeM\" \/><input type=\"hidden\" name=\"gateway\" value=\"gw_TlTNIsHSf5lh85\" \/><input type=\"hidden\" name=\"integrity_value\" value=\"8cc1e258bfb0e8d7371ef068433b79b9ae910a48\" \/><input type=\"submit\" value=\"0\" \/><\/form><\/body><\/html>"
}

Form for upgrading existing subscriptions

This call will build a form so customers can upgrade or downgrade existing subscriptions through any gateway you have registered at Peakium.

Arguments

Name Required Description
customer required The reference id for your customer object in your application.
subscription required The reference id for your customer-specific subscription object in your application.
items required A list of items the subscription has
items>item_id required
items>item_description required
items>unit_amount required
items>currency optional
items>quantity optional
items>discount optional
period_amount required Number of days, months or years
period_type required day, month or year
payment_currency required If currency in an item is set this is not needed
return_url_ok required
return_url_error required
pro_rata optional
gateway optional If not defined, the gateway parameter will be set automatically depending on default payment method for your customer, and your default gateway.
submit_button_text optional What text the submit button should contain. Default is "Click here if you are not redirected within 10 seconds".
auto_submit_page optional A boolean value representing if the returning HTML should include the full auto submit page. If false, or undefined, only the form element will be returned.
auto_submit_page_title optional A string for the title to display in the auto submit page. Default is "Redirecting to payment method..."

Example request

curl https://secure.peakium.com/api/v1/submission_form/update-subscription/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -p customer="cu4321" \
    -p subscription="50aaeccb73dd310010" \
    -p item_description="Plus Plan" \
    -p item_id=101 \
    -p period_amount=1 \
    -p period_type="month" \
    -p payment_amount=7200 \
    -p payment_currency="USD" \
    -p payment_discount=0.0 \
    -p return_url_ok="http://example.org/payment/success/" \
    -p return_url_error="http://example.org/payment/error/" \
    -p auto_submit_page=true

Example response

{
    "html": "<!DOCTYPE html PUBLIC \"-\/\/W3C\/\/DTD XHTML 1.0 Transitional\/\/EN\" \"http:\/\/www.w3.org\/TR\/xhtml1\/DTD\/xhtml1-transitional.dtd\"><html xmlns=\"http:\/\/www.w3.org\/1999\/xhtml\"><head><title>Redirecting to payment method...<\/title><\/head><body><h3>Redirecting to payment method...<\/h3><body onload=\"document.p.submit();\"><form action=\"http:\/\/secure.peakium.com\/update-subscription\/\" method=\"post\" name=\"p\"><input type=\"hidden\" name=\"action\" value=\"update\" \/><input type=\"hidden\" name=\"customer\" value=\"cu4321\" \/><input type=\"hidden\" name=\"subscription\" value=\"50aaeccb73dd310010\" \/><input type=\"hidden\" name=\"item_description\" value=\"Plus Plan\" \/><input type=\"hidden\" name=\"item_id\" value=\"101\" \/><input type=\"hidden\" name=\"period_amount\" value=\"1\" \/><input type=\"hidden\" name=\"period_type\" value=\"month\" \/><input type=\"hidden\" name=\"payment_amount\" value=\"7200\" \/><input type=\"hidden\" name=\"payment_currency\" value=\"USD\" \/><input type=\"hidden\" name=\"payment_discount\" value=\"0\" \/><input type=\"hidden\" name=\"return_url_ok\" value=\"http:\/\/example.org\/payment\/success\/\" \/><input type=\"hidden\" name=\"return_url_error\" value=\"http:\/\/example.org\/payment\/error\/\" \/><input type=\"hidden\" name=\"publishable_key\" value=\"pk_QTBkCKdRworbXYZens4V4LZZs1X00FeM\" \/><input type=\"hidden\" name=\"gateway\" value=\"gw_TlTNIsHSf5lh85\" \/><input type=\"hidden\" name=\"integrity_value\" value=\"8cc1e258bfb0e8d7371ef068433b79b9ae910a48\" \/><input type=\"submit\" value=\"0\" \/><\/form><\/body><\/html>"
}

Form for paying existing invoices

This call will build a form so customers can pay invoices through any gateway you have registered at Peakium. It is useful for invoices that cannot be charged automatically (e.g. overdue invoices).

Arguments

Name Required Description
customer required The reference id for your customer object in your application.
invoice required The id for the invoice object at Peakium.
return_url_ok required
return_url_error required
gateway optional If not defined, the gateway parameter will be set automatically depending on default payment method for your customer, and your default gateway.
submit_button_text optional What text the submit button should contain. Default is "Click here if you are not redirected within 10 seconds".
auto_submit_page optional A boolean value representing if the returning HTML should include the full auto submit page. If false, or undefined, only the form element will be returned.
auto_submit_page_title optional A string for the title to display in the auto submit page. Default is "Redirecting to payment method..."

Example request

curl https://secure.peakium.com/api/v1/submission_form/pay-invoice/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -p customer="cu4321" \
    -p invoice="in_TlQFJ1ZvXfuX2g" \
    -p return_url_ok="http://example.org/payment/success/" \
    -p return_url_error="http://example.org/payment/error/"

Example response

{
    "html": "<form action=\"http:\/\/secure.peakium.com\/pay-invoice\/in_TlQFJ1ZvXfuX2g\/\" method=\"post\" name=\"p\"><input type=\"hidden\" name=\"customer\" value=\"cu4321\" \/><input type=\"hidden\" name=\"invoice\" value=\"in_TlQFJ1ZvXfuX2g\" \/><input type=\"hidden\" name=\"return_url_ok\" value=\"http:\/\/example.org\/payment\/success\/\" \/><input type=\"hidden\" name=\"return_url_error\" value=\"http:\/\/example.org\/payment\/error\/\" \/><input type=\"hidden\" name=\"publishable_key\" value=\"pk_QTBkCKdRworbXYZens4V4LZZs1X00FeM\" \/><input type=\"hidden\" name=\"gateway\" value=\"gw_TlTNIsHSf5lh85\" \/><input type=\"hidden\" name=\"integrity_value\" value=\"b860f950df56104a9328e44f6b3ce6e30f6db55a\" \/><input type=\"submit\" value=\"0\" \/><\/form>"
}

Form for single payments

At times you might want customers to just pay a one-time fee. This call will build a form for paying one or more items.

Arguments

Name Required Description
customer required The reference id for your customer object in your application.
items required A list of items to pay
items>item_id required
items>item_description required
items>unit_amount required
items>currency required
items>quantity required
items>discount required
return_url_ok required
return_url_error required
gateway optional If not defined, the gateway parameter will be set automatically depending on default payment method for your customer, and your default gateway.
submit_button_text optional What text the submit button should contain. Default is "Click here if you are not redirected within 10 seconds".
auto_submit_page optional A boolean value representing if the returning HTML should include the full auto submit page. If false, or undefined, only the form element will be returned.
auto_submit_page_title optional A string for the title to display in the auto submit page. Default is "Redirecting to payment method..."

Example request

curl https://secure.peakium.com/api/v1/submission_form/single-payment/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -p customer="cu4321" \
    -p items[0][item_id]=1 \
    -p items[0][item_description]="Setup fee" \
    -p items[0][unit_amount]=599 \
    -p items[0][currency]="USD" \
    -p items[0][quantity]=1" \
    -p items[0][discount]=0.0 \
    -p items[1][item_id]=2 \
    -p items[1][item_description]="1 hour support" \
    -p items[1][unit_amount]=999 \
    -p items[1][currency]="USD" \
    -p items[1][quantity]=1" \
    -p items[1][discount]=0.0 \
    -p return_url_ok="http://example.org/payment/success/" \
    -p return_url_error="http://example.org/payment/error/"

Example response

{
    "html": "<form action=\"http:\/\/secure.peakium.com\/single-payment\/\" method=\"post\" name=\"p\"><input type=\"hidden\" name=\"customer\" value=\"cu4321\" \/><input type=\"hidden\" name=\"items[0][item_id]\" value=\"1\" \/><input type=\"hidden\" name=\"items[0][item_description]\" value=\"Setup fee\" \/><input type=\"hidden\" name=\"items[0][unit_amount]\" value=\"599\" \/><input type=\"hidden\" name=\"items[0][currency]\" value=\"USD\" \/><input type=\"hidden\" name=\"items[0][quantity]\" value=\"1\" \/><input type=\"hidden\" name=\"items[0][discount]\" value=\"0.0\" \/><input type=\"hidden\" name=\"items[1][item_id]\" value=\"2\" \/><input type=\"hidden\" name=\"items[1][item_description]\" value=\"1 hour support\" \/><input type=\"hidden\" name=\"items[1][unit_amount]\" value=\"999\" \/><input type=\"hidden\" name=\"items[1][currency]\" value=\"USD\" \/><input type=\"hidden\" name=\"items[1][quantity]\" value=\"1\" \/><input type=\"hidden\" name=\"items[1][discount]\" value=\"0.0\" \/><input type=\"hidden\" name=\"return_url_ok\" value=\"http:\/\/example.org\/payment\/success\/\" \/><input type=\"hidden\" name=\"return_url_error\" value=\"http:\/\/example.org\/payment\/error\/\" \/><input type=\"hidden\" name=\"publishable_key\" value=\"pk_QTBkCKdRworbXYZens4V4LZZs1X00FeM\" \/><input type=\"hidden\" name=\"gateway\" value=\"gw_TlTNIsHSf5lh85\" \/><input type=\"hidden\" name=\"integrity_value\" value=\"b860f950df56104a9328e44f6b3ce6e30f6db55a\" \/><input type=\"submit\" value=\"0\" \/><\/form>"
}

Subscription


A subscription object is always tied to a Customer. The subscription token is only unique within the customer scope, thus it is possible to reuse the same subscription token for different customers. For this reason, when you are handling individual subscriptions, you are always required to use the Customer resource.

A subscription can be created by a customer through the submission form. The subscription object can be cancelled through the API.

The subscription object

Attributes

Name Type Description
token string The token is under the scope of a customer
object string Will be "subscription"
created integer
plan array
plan->period_amount integer
plan->period_type string day, month or year
plan->items object A list of items the subscription has
plan->items>item_id required
plan->items>item_description required
plan->items>unit_amount required
plan->items>currency optional
plan->items>quantity optional
plan->items>discount optional
plan->currency string
cycle_number integer
period_start integer
period_end integer
next_charge integer
status string
customer object
metadata object

Example

{
    "token": "50aaeccb73dd310010",
    "object": "subscription",
    "created": 1375217068,
    "display_name": "Plus Plan",
    "plan": {
        "period_amount": 1,
        "period_type": "month",
        "amount": 7200,
        "currency": "USD",
        "discount": 0.0,
        "item_id": 101
    },
    "cycle_number": 1,
    "period_start": 1375217068,
    "period_end": 1375217068,
    "next_charge": 1375217068,
    "status": "active",
    "customer": "cu4321",
    "metadata": {}
}

List all subscriptions

Returns a list of all subscriptions.

Arguments

Name Required Description
count optional
offset optional
customer optional

Example request

$ curl https://secure.peakium.com/api/v1/subscriptions/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "token": "50aaeccb73dd310010",
            "object": "subscription",
            "created": 1375217068,
            "display_name": "Plus Plan",
            "plan": {
                "period_amount": 1,
                "period_type": "month",
                "amount": 7200,
                "currency": "USD",
                "discount": 0.0,
                "item_id": 101
            },
            "cycle_number": 1,
            "period_start": 1375217068,
            "period_end": 1375217068,
            "next_charge": 1375217068,
            "status": "active",
            "customer": "cu4321",
            "metadata": {}
        },
        {...}
    ]
}

List all subscriptions for a specific customer

Returns a list of all subscriptions for a specific customer.

Arguments

Name Required Description
count optional
offset optional

Example request

$ curl https://secure.peakium.com/api/v1/customers/cu4321/subscriptions/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "token": "50aaeccb73dd310010",
            "object": "subscription",
            "created": 1375217068,
            "display_name": "Plus Plan",
            "plan": {
                "period_amount": 1,
                "period_type": "month",
                "amount": 7200,
                "currency": "USD",
                "discount": 0.0,
                "item_id": 101
            },
            "cycle_number": 1,
            "period_start": 1375217068,
            "period_end": 1375217068,
            "next_charge": 1375217068,
            "status": "active",
            "customer": "cu4321",
            "metadata": {}
        },
        {...}
    ]
}

Retrieve a specific subscription

To retrieve a specific subscription resource, you need to use the Customer resource for the subscription in the URI.

Example request

$ curl https://secure.peakium.com/api/v1/customers/cu4321/subscriptions/50aaeccb73dd310010/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "token": "50aaeccb73dd310010",
    "object": "subscription",
    "display_name": "Plus Plan",
    "plan": {
        "period_amount": 1,
        "period_type": "month",
        "amount": 7200,
        "currency": "USD",
        "discount": 0.0,
        "item_id": 101
    },
    "cycle_number": 1,
    "period_start": 1375217068,
    "period_end": 1375217068,
    "next_charge": 1375217068,
    "status": "active",
    "customer": "cu4321",
    "metadata": {}
}

Cancel a subscription

This will cancel an active subscription, and stop any future charges. A cancelled subscription cannot be reactivated.

You need to use the Customer resource for the subscription in the URI to cancel a subscription.

Example request

$ curl https://secure.peakium.com/api/v1/customers/cu4321/subscriptions/50aaeccb73dd310010/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -X DELETE

Example response

{
    "token": "50aaeccb73dd310010",
    "object": "subscription",
    "created": 1375217068,
    "display_name": "Plus Plan",
    "plan": {
        "period_amount": 1,
        "period_type": "month",
        "amount": 7200,
        "currency": "USD",
        "discount": 0.0,
        "item_id": 101
    },
    "cycle_number": 1,
    "period_start": 1375217068,
    "period_end": 1375217068,
    "next_charge": 1375217068,
    "status": "cancelled",
    "customer": "cu4321",
    "metadata": {}
}

Webhook


Webhook objects define the URL endpoints for webhooks.

The webhook object

Attributes

Name Type Description
object string Will be "webhook"
created integer
url string

Example

{
    "object": "webhook",
    "created": 1375217068,
    "url": "http://example.com/webhook_endpoint/"
}

List all webhooks

Returns a list of all webhooks.

Arguments

Name Required Description
count optional
offset optional

Example request

$ curl https://secure.peakium.com/api/v1/webhooks/?count=2 \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9:

Example response

{
    "object": "list",
    "count": 2,
    "data": [
        {
            "object": "webhook",
            "created": 1375217068,
            "url": "http://example.com/webhook_endpoint/"
        },
        {...}
    ]
}

Create a webhook

A webhook can be created over the API.

Arguments

Name Required Description
url required The webhook URL endpoint

Example request

$ curl https://secure.peakium.com/api/v1/webhooks/ \
    -u pk_gEVUPX6FwObZSgg3v0BjkVxmdzatPyV9: \
    -d url="http://example.com/webhook_endpoint/"

Example response

Will respond with 200 OK status, and the full webhook object if valid, or fail with failure HTTP status code.