NAV Navbar
Kovena logo brandmark design dark
shell JavaScript

Introduction

The Kovena platform is designed to be as simple and easy to use as possible.

There is REST API, giving you full control to Kovena:

Getting started

You can get up and running using the Kovena API in just a few minutes.

Start by signing up for a sandbox account. This will give you access to the admin portal.

From the admin portal you can connect services. If you do not already have services to connect, you can usually sign up for test accounts You can see a list of some of the services we support here.

Then add a gateway in Gateway --> Add New:

Add Gateway

You can retrieve your API public and secret key from the admin portal in My Company --> API & Settings, which you'll need to authenticate:

API public key

Once done, jump into one of our Recipes:

Key Concepts

There are a few key concepts that help understand how to get the most out of Kovena's Platform

Concept Description
one-time token This is a token that represents payment information. One time tokens expire after 3 hours.
payment source A payment source represents a way of paying for something. This could be credit card details, bank account details or a PayPal account. There can be multiple payment sources associated with a customer.
gateway A gateway is a payment gateway of any type that payments are routed to, eg Braintree, PayPal.
vault The vault is Kovena's PCI compliant storage vault of payment sources.
vault token A vault token is the reference code for a payment source, eg a credit card and expiry date
subscription A subscription is a scheduled payment plan for a customer.
sandbox A sandbox environment is a place where test API calls can be made without charging customers.
customer An individual who can make payments.
admin portal Web interface to manage your Kovena account

Endpoints

An endpoint is a unique URL that represents an object or collection of objects which serves as the base of all Kovena API interactions.

Kovena provides two different public environments to access. You can access the different environments from the following URLS:

Environment API Admin portal
Sandbox https://api-sandbox.kovena.com https://app-sandbox.kovena.com
Production https://api.kovena.com https://app.kovena.com

To set up API calls, prepend all calls with:

Throughout the documentation URLs are provided relative to these base URLs.

eg GET /v1/gateways for Sandbox, represents

GET https://api-sandbox.kovena.com/v1/gateways

eg GET /v1/gateways for Production, represents

GET https://api.kovena.com/v1/gateways

Authentication

Authenticate with our API is provided by providing either your API Public Key or API Secret Key, depending on how you are using the Kovena platform. These are 40 character strings which you can find in out web app: API public key

Authentication is managed slightly differently depending on how you're connecting to Kovena.

Connecting to the Kovena from the client side is managed through the Public Key.

All other authentication is through the API Secret Key. This is used to secure server side calls:

Response codes / Error codes

Kovena's API follows REST principles on status codes returned from our API.

In addition, the API will generally return a detailed error message and any downstream errors. See the right panel for examples

HTTP code Meaning Description Request type
200 Call successful Appears on success request any
201 Created successfully Appears on success request while creating new resource POST
400 Merchant data error There is also an error code in response. Check the "error_summary" section for the details. any
403 Permission denied Authorization token does not have permission any
404 Resource not found The requested resource by id is not found for your visibility scope any
500 System error Unexpected server error any
408 API unavailable Only for .Net SDK. The response from the .Net SDK when it can't reach the API for some time any

In addition, the API will generally return a detailed error message and any downstream errors. See the right panel for examples


"Gateway processing error"

"error_summary": {
        "message": "Transaction Declined",
        "code": "transaction_declined",
        "status_code": "05",
        "status_code_description": "Do not honour",
        "details": {
            "gateway_specific_code": "DECLINED",
            "gateway_specific_description": "The requested operation was not successful",
            "messages": [
                "Transaction Declined"
            ]
        }
    }

http code

Cause

Error Code

Error Structure

400

Internal validation

  • validation_error

  • required_error

  • unfulfilled_condition

{
message: string,
code: string,
details: {
path?: string,
messages: string[]
} }

400

gateway validation

  • gateway_error

  • insufficient_funds

  • сredit_card_invalid_or_expired

  • transaction_declined

  • transaction_declined_hard

  • system_error

  • fraud_warning

  • invalid_transaction_details

  • unknown

{
message: string,
code: string,
details: {
path?: string,
gateway_specific_code: string,
gateway_specific_description: string
messages: string[]
} }

400

gateway proccesing

  • gateway_error

  • insufficient_funds

  • сredit_card_invalid_or_expired

  • transaction_declined

  • transaction_declined_hard

  • system_error

  • fraud_warning

  • invalid_transaction_details

  • unknown

{ message: string,
code: string,
status_code: string,
status_code_description: string,
details: {
path?: string,
gateway_specific_code: string,
gateway_specific_description: string
messages: string[]
} }

400 - 599

other

  • unspecified_error

  • *

{
message: string,
code: string,
details: {
messages: string[]
} }

Kovena vault

"Example response with vault token"
{
  "status": 201,
  "error": null,
  "resource": {
    "type": "customer",
    "data": {
      "__v": 0,
      "created_at": "2017-01-24T23:28:14.045Z",
      "updated_at": "2017-01-24T23:28:14.045Z",
      "status": "active",
      "default_source": "5887e30d28e281756b883f64",
      "reference": "Fuga consequuntur sint ab magnam",
      "first_name": "Natalie",
      "last_name": "Foster",
      "email": "nwashington@gmail.com",
      "_id": "5887e30c28e281756b883f63",
      "payment_sources": [
        {
          "updated_at": "2017-01-24T23:28:14.045Z",
          "vault_token": "dd634c0c-ea3b-4d82-b7fb-5ef2d2949ff6",
          "gateway_id": "58377235377aea03343240cc",
          "card_name": "Natalie Foster",
          "expire_month": 1,
          "expire_year": 2019,
          "card_number_last4": "1111",
          "card_scheme": "visa",
          "ref_token": "53774915",
          "status": "active",
          "created_at": "2017-01-24T23:28:13.826Z",
          "_id": "5887e30d28e281756b883f64",
          "type": "card"
        }
      ],
      "statistics": {
        "total_collected_amount": 0,
        "successful_transactions": 0
      },
      "_service": {
        "default_gateway_id": "58377235377aea03343240cc"
      }
    }
  }
}

Kovena provides a PCI compliant vault for payment details. When the vault is enabled, all payment details are stored in the vault. The vault is enabled or disabled across a whole Kovena account, rather than for individual requests.

When the vault is enabled, any time a payment source is added, this information is stored in the vault. This most commonly happens when a payment source is added to a customer or a new customer is created. This is also visible in the response, which includes the id for the vault token, see example to the right (payment_sources -> vault_token).

Access tokens

With the help of access tokens, you can grant your Kovena integration particular permissions based on your needs. An access token can be used as a header for making API requests instead of public and secret API keys. You can create an unlimited number of access tokens with various permissions and a configurable expiry.

field required type description
label - string Name of the access token to identify it further
expiration_in - number (seconds) Time period in seconds after which the access token will expire
permissions + string Actions the user will be able to perform with the access token

Here is how it looks in the dashboard when you click ‘Create New’: Access token create

You can generate an external access token in your Kovena dashboard if your role has the corresponding privileges. You can give only those permissions to this token which are enabled for your role.

You can set permissions for individual endpoints. For example, instead of granting all charge-related permissions (creating, modifying, searching, getting by ID, archiving, etc.), you can choose only specific ones. As a result, your token could be used only for searching charges but not for creating them.

You can deactivate an access token at any time. It can be useful for cases when you delegate some work on integration to third-party developers. Once the work is done, you can deactivate the token without worrying that it can be used for some unauthorized actions. Access token deactivate

The usage of an access token can be tracked as well. You can view the statistics in the Profile menu -> ‘Audit’ in the dashboard.

API Reference

The Kovena API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate URL to perform a live or test transaction. Requests made with test mode credentials never hit the banking networks and incur no cost.

Kovena users can interact with the service in a number of ways.

Visit Kovena Postman documentation page:

Visit API Reference

 

Or visit Kovena Master Merchant (Brand) documentation:

Visit API Reference

Other Resources

Fraud detection service

Available only if configured for your account. Kovena Fraud detection API has an ability to operate in 'active' mode where Kovena will: Collect and report but also take the following actions

Or in ‘passive' mode (where Kovena collects and reports, but does not respond to Fraud Service responses, and doesn’t block transaction processing)

Kovena API returns all fraud-related response data inside the "fraud" section of each processed transaction.

Fraud Data Description

Field Name Description Possible values
score Overall score of the fraud risk. Bigger number means bigger risk Optional. Not all fraud providers return it. Numeric
status Service-agnostic recommendation from Kovena on the base of the service response "approve", "reject", "review", "failed"
specific_code Fraud service specific code Depends on the fraud service
specific_message Explanation of the code, coming from the fraud service Human-readable text

Testing

Kovena Fraud API in the Sandbox mode is set to return custom results based on the email. While creating one-time token request use "email" key or on tha stage of creating a charge with fraud check use "fraud.data.transaction.billing.customerEmailAddress" key to reproduce different type of responses:

Email value Fraud status
reject@example.com reject
review@example.com review
failed@example.com failed
any other approve

Also Kovena Fraud API in the Sandbox mode is set to return custom results based on the transaction amount.

Amount Fraud status
101 reject
102 review
103 failed
any other approve

Fraud API response examples

Required Fields by Gateway

Different gateways require different fields, see detailed listing below

Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name required
last_name required
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email required
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name required
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email required
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country required
address_postcode required
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name required
last_name required
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 required
address_line2 optional
address_city required
address_state required
address_country required
address_postcode required
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email required
address_line1 optional
address_line2 optional
address_city required
address_state required
address_country required
address_postcode required
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
account_routing n/a
account_holder_type n/a
account_bank_name n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month optional
expire_year optional
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name optional
account_bsb required
account_number required
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city required
address_state required
address_country required
address_postcode required
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city required
address_state required
address_country required
address_postcode required
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb required
account_number required
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name required
card_number required
expire_month required
expire_year required
card_ccv required
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv optional
type n/a
account_name n/a
account_bsb n/a
account_number n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email required
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country required
address_postcode required
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required
type n/a
account_name n/a
account_bsb n/a
account_number n/a
Field Name Options
amount required
currency required
reference optional
description optional
first_name required
last_name optional
email required
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country required
address_postcode optional
gateway_id required
card_name n/a
card_number n/a
expire_month n/a
expire_year n/a
card_ccv n/a
type required
account_name required
account_bsb n/a
account_number required
account_routing required
account_type required
account_holder_type required
account_bank_name required
Field Name Options
amount required
currency required
reference optional
description optional
first_name optional
last_name optional
email optional
address_line1 optional
address_line2 optional
address_city optional
address_state optional
address_country optional
address_postcode optional
gateway_id required
card_name optional
card_number required
expire_month required
expire_year required
card_ccv required

Swap Values for templates

The notification templates can be used to load parameters from the customer or transaction into the notification. These can also be used to populate the destination (eg phone number for sms).

The full list of available swap values is:

Field Name Description
{{CHARGE_ID}} Kovena ID for the charge
{{EMAIL}} The email address for the customer associated with the event
{{FIRST_NAME}} The first name for the customer associated with the event
{{LAST_NAME}} The last name for the customer associated with the event
{{PHONE}} The phone number for the customer associated with the event
{{AMOUNT}} The amount for the transaction
{{CURRENCY}} The currency for the transation
{{CUSTOMER_REFERENCE}} The customer reference number provided by the merchant for the customer
{{CHARGE_REFERENCE}} The reference number provided by the merchant for the transaction
{{CHARGE_DESCRIPTION}} The description provided by the merchant for the transaction
{{CREATED_AT}} create date for the object (eg customer, subscription) in ISO format date and time (eg 2016-12-22T10:36:08.170Z)
{{UPDATED_AT}} updated date for the object (eg customer, subscription) in ISO format date and time (eg 2016-12-22T10:36:08.170Z)

Webhook event example

"Example of Transaction Success"
{
    "event": "transaction_success",
    "data": {
        "external_id": "ch_A5UQxvnd7B1aC2",
        "_id": "589c848fc1ecdd2a29fd2197",
        "created_at": "2017-02-09T15:02:39.971Z",
        "updated_at": "2017-02-09T15:02:41.498Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "reference": "Reprehenderit laborum ea a optio iusto quis",
        "description": "Quidem in ea maiores illo quos esse",
        "__v": 1,
        "transactions": [
            {
                "created_at": "2017-02-09T15:02:39.968Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589c848fc1ecdd2a29fd2198",
                "status": "complete",
                "type": "sale"
            }
        ],
        "one_off": true,
        "archived": false,
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "reference": "Quidem in ea maiores illo quos esse",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4444",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_state": null,
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_scheme": "mastercard",
                "gateway_name": "Gateway Name",
                "gateway_type": "GatewayType"
            }
        },
        "status": "complete"
    }
}

Kovena supports the following webhook events (see payload examples to the right):

"Example of Transaction Failure"
{
    "event": "transaction_failure",
    "data": {
        "_id": "589da11f1958cb42532f2463",
        "created_at": "2017-02-10T11:16:47.538Z",
        "updated_at": "2017-02-10T11:16:48.480Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "__v": 1,
        "transactions": [
            {
                "created_at": "2017-02-10T11:16:47.533Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589da11f1958cb42532f2464",
                "status": "failed",
                "type": "sale"
            }
        ],
        "one_off": true,
        "archived": false,
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4445",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_state": null,
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_scheme": "mastercard",
                "gateway_name": "Gateway Name",
                "gateway_type": "GatewayType"
            }
        },
        "status": "failed"
    }
}
"Example of Transaction by Subscription Success"
{
    "event": "subscription_transaction",
    "data": {
        "_id": "589da11f1958cb42532f2463",
        "created_at": "2017-02-10T11:16:47.538Z",
        "updated_at": "2017-02-10T11:16:48.480Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589dae7aa6c87450a798348e",
        "__v": 1,
        "transactions": [
            {
                "created_at": "2017-02-10T11:16:47.533Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589da11f1958cb42532f2464",
                "status": "failed",
                "type": "sale"
            }
        ],
        "one_off": true,
        "archived": false,
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4445",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_state": null,
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_scheme": "mastercard",
                "gateway_name": "Gateway Name",
                "gateway_type": "GatewayType"
            }
        },
        "status": "complete"
    }
}
"Example of Transaction by Subscription Failed"
{
    "event": "subscription_transaction_failure",
    "data": {
        "_id": "589da11f1958cb42532f2463",
        "created_at": "2017-02-10T11:16:47.538Z",
        "updated_at": "2017-02-10T11:16:48.480Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589dae7aa6c87450a798348e",
        "__v": 1,
        "transactions": [
            {
                "created_at": "2017-02-10T11:16:47.533Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589da11f1958cb42532f2464",
                "status": "failed",
                "type": "sale"
            }
        ],
        "one_off": true,
        "archived": false,
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4445",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_state": null,
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_scheme": "mastercard",
                "gateway_name": "Gateway Name",
                "gateway_type": "GatewayType"
            }
        },
        "status": "failed"
    }
}
"Example of Subscription Creation Success"
{
    "event": "subscription_creation_success",
    "data": {
        "__v": 0,
        "created_at": "2017-02-10T11:55:59.804Z",
        "updated_at": "2017-02-10T11:55:59.804Z",
        "amount": 111,
        "payment_source_id": "589daa4fa6c87450a798347d",
        "status": "active",
        "_id": "589daa4fa6c87450a798347f",
        "archived": false,
        "_service": {
            "customer_default_gateway_id": "56a8ab12d6bd4e7d628576aa",
            "tags": "Samantha Washington samwashington@gmail.com"
        },
        "customer": {
            "customer_id": "589daa4ea6c87450a798347c",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000"
        },
        "statistics": {
            "total_collected_amount": 0,
            "successful_transactions": 0
        },
        "schedule": {
            "interval": "week",
            "start_date": "2017-02-10T11:55:58.477Z",
            "next_assessment": "2017-02-10T11:55:58.477Z",
            "next_assessment_planned": "2017-02-10T11:55:58.477Z",
            "first_assessment": "2017-02-10T11:55:58.477Z",
            "status": "inprogress",
            "locked": false,
            "completed_count": 0,
            "retry_count": 0,
            "frequency": 2
        },
        "currency": "AUD"
    }
}
"Example of Subscription Creation Failure"
{
    "event": "subscription_creation_failure",
    "data": {
        "customer": {
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "address_country": "AU",
                "type": "card",
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "gateway_id": "56a8ab12d6bd4e7d628576aa",
                "card_name": "Samantha Washington",
                "card_number_last4": "4445",
                "expire_month": "**",
                "expire_year": "****",
                "card_ccv": "***"
            },
            "_check_expire_date": false
        },
        "amount": "111",
        "currency": "AUD"
    }
}
"Example of Subscription Finished"
{
    "event": "subscription_finished",
    "data": {
        "_id": "589dacaf1958cb42532f2482",
        "created_at": "2017-02-10T12:06:07.575Z",
        "updated_at": "2017-02-10T12:06:19.146Z",
        "amount": 111,
        "payment_source_id": "589dacaf1958cb42532f2480",
        "status": "expired",
        "__v": 0,
        "archived": false,
        "_service": {
            "customer_default_gateway_id": "56a8ab12d6bd4e7d628576aa",
            "tags": "Samantha Washington samwashington@gmail.com",
            "queue_id": "QU-DD034F558CB0C576"
        },
        "customer": {
            "customer_id": "589dacae1958cb42532f247f",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000"
        },
        "statistics": {
            "total_collected_amount": 111,
            "successful_transactions": 1
        },
        "schedule": {
            "last_assessment": "2017-02-10T12:06:19.143Z",
            "interval": "week",
            "start_date": "2017-02-10T12:06:06.596Z",
            "end_date": "2017-02-11T00:00:00.000Z",
            "next_assessment": "2017-02-10T12:06:06.596Z",
            "next_assessment_planned": "2017-02-10T12:06:06.596Z",
            "first_assessment": "2017-02-10T12:06:06.596Z",
            "status": "complete",
            "locked": false,
            "completed_count": 1,
            "retry_count": 0,
            "frequency": 1
        },
        "currency": "AUD"
    }
}
"Example of Subscription Updated"
{
    "event": "subscription_updated",
    "data": {
        "_id": "589dae7aa6c87450a798348e",
        "created_at": "2017-02-10T12:13:46.059Z",
        "updated_at": "2017-02-10T12:14:39.872Z",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "amount": 111,
        "payment_source_id": "589dae79a6c87450a798348c",
        "_source_ip_address": "159.224.44.130",
        "status": "active",
        "archived": false,
        "customer": {
            "customer_id": "589dae78a6c87450a798348b",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000"
        },
        "statistics": {
            "total_collected_amount": 111,
            "successful_transactions": 1
        },
        "schedule": {
            "end_amount_total": null,
            "end_amount_before": null,
            "end_transactions": null,
            "end_amount_after": null,
            "end_date": null,
            "interval": "day",
            "start_date": "2017-02-12T00:00:00.000Z",
            "next_assessment": "2017-02-12T00:00:00.000Z",
            "next_assessment_planned": "2017-02-12T00:00:00.000Z",
            "first_assessment": "2017-02-12T00:00:00.000Z",
            "status": "complete",
            "last_assessment": "2017-02-10T12:13:49.469Z",
            "locked": false,
            "completed_count": 1,
            "retry_count": 0,
            "frequency": 1
        },
        "currency": "AUD",
        "gateway_type": "GatewayType",
        "gateway_name": "Gateway Name",
        "gateway_mode": "test"
    }
}
"Example of Subscription Failed"
{
    "event": "subscription_failed",
    "data": {
        "_id": "589dae7aa6c87450a798348e",
        "created_at": "2017-02-10T12:13:46.059Z",
        "updated_at": "2017-02-10T12:14:39.872Z",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "amount": 111,
        "payment_source_id": "589dae79a6c87450a798348c",
        "_source_ip_address": "159.224.44.130",
        "status": "active",
        "archived": false,
        "customer": {
            "customer_id": "589dae78a6c87450a798348b",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000"
        },
        "statistics": {
            "total_collected_amount": 111,
            "successful_transactions": 1
        },
        "schedule": {
            "interval": "day",
            "start_date": "2017-02-12T00:00:00.000Z",
            "next_assessment": "2017-02-12T00:00:00.000Z",
            "next_assessment_planned": "2017-02-12T00:00:00.000Z",
            "first_assessment": "2017-02-12T00:00:00.000Z",
            "status": "complete",
            "last_assessment": "2017-02-10T12:13:49.469Z",
            "locked": false,
            "completed_count": 1,
            "retry_count": 0,
            "frequency": 1
        },
        "currency": "AUD",
        "gateway_type": "GatewayType",
        "gateway_name": "Gateway Name",
        "gateway_mode": "test"
    }
}
"Example of Refund Requested"
{
    "event": "refund_requested",
    "data": {
        "_id": "589dae7c1958cb42532f248a",
        "created_at": "2017-02-10T12:13:48.034Z",
        "updated_at": "2017-02-10T12:16:53.495Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589dae7aa6c87450a798348e",
        "__v": 3,
        "external_id": "ch_A5ovQPHUOTprV7",
        "transactions": [
            {
                "created_at": "2017-02-10T12:13:48.029Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589dae7c1958cb42532f248b",
                "status": "complete",
                "type": "sale"
            },
            {
                "pended_at": "2017-02-11T12:16:53.509Z",
                "created_at": "2017-02-10T12:16:51.582Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589daf33a6c87450a7983491",
                "status": "requested",
                "type": "refund"
            }
        ],
        "one_off": false,
        "archived": false,
        "customer": {
            "customer_id": "589dae78a6c87450a798348b",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4444",
                "card_scheme": "mastercard",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa"
            }
        },
        "status": "refund_requested",
        "transaction": {
            "pended_at": "2017-02-11T12:16:53.509Z",
            "created_at": "2017-02-10T12:16:51.582Z",
            "amount": 111,
            "currency": "AUD",
            "_id": "589daf33a6c87450a7983491",
            "status": "requested",
            "type": "refund"
        }
    }
}
"Example of Refund Success"
{
    "event": "refund_success",
    "data": {
        "_id": "589dae7c1958cb42532f248a",
        "created_at": "2017-02-10T12:13:48.034Z",
        "updated_at": "2017-02-10T12:19:05.117Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589dae7aa6c87450a798348e",
        "__v": 4,
        "external_id": "ch_A5ovQPHUOTprV7",
        "transactions": [
            {
                "created_at": "2017-02-10T12:13:48.029Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589dae7c1958cb42532f248b",
                "status": "complete",
                "type": "sale"
            },
            {
                "created_at": "2017-02-10T12:16:51.582Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589daf33a6c87450a7983491",
                "pended_at": "2017-02-11T12:16:53.509Z",
                "status": "complete",
                "type": "refund"
            }
        ],
        "one_off": false,
        "archived": false,
        "customer": {
            "customer_id": "589dae78a6c87450a798348b",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4444",
                "card_scheme": "mastercard",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_postcode": "1111",
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa"
            }
        },
        "status": "refunded",
        "transaction": {
            "created_at": "2017-02-10T12:16:51.582Z",
            "amount": 111,
            "currency": "AUD",
            "_id": "589daf33a6c87450a7983491",
            "pended_at": "2017-02-11T12:16:53.509Z",
            "status": "complete",
            "type": "refund"
        }
    }
}
"Example of Refund Failure"
{
    "event": "refund_failure",
    "data": {
        "_id": "589daa621958cb42532f2476",
        "created_at": "2017-02-10T11:56:18.021Z",
        "updated_at": "2017-02-10T12:24:56.723Z",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "amount": 111,
        "currency": "AUD",
        "subscription_id": "589daa4fa6c87450a798347f",
        "__v": 3,
        "external_id": "ch_A5odfEhbA7VaT1",
        "transactions": [
            {
                "created_at": "2017-02-10T11:56:18.017Z",
                "amount": 111,
                "currency": "AUD",
                "_id": "589daa621958cb42532f2477",
                "status": "complete",
                "type": "sale"
            },
            {
                "created_at": "2017-02-10T12:24:55.732Z",
                "amount": 11111111111,
                "currency": "AUD",
                "_id": "589db1171958cb42532f2497",
                "status": "failed",
                "type": "refund"
            }
        ],
        "one_off": false,
        "archived": false,
        "customer": {
            "customer_id": "589daa4ea6c87450a798347c",
            "first_name": "Samantha",
            "last_name": "Washington",
            "email": "samwashington@gmail.com",
            "phone": "+61000000000",
            "payment_source": {
                "type": "card",
                "card_name": "Samantha Washington",
                "card_number_last4": "4444",
                "card_scheme": "mastercard",
                "expire_month": 1,
                "expire_year": 2019,
                "address_line1": "Suite 660",
                "address_line2": "822 Ruiz Square",
                "address_city": "Sydney",
                "address_country": "AU",
                "gateway_id": "56a8ab12d6bd4e7d628576aa"
            }
        },
        "status": "complete",
        "transaction": {
            "created_at": "2017-02-10T12:24:55.732Z",
            "amount": 11111111111,
            "currency": "AUD",
            "_id": "589db1171958cb42532f2497",
            "status": "failed",
            "type": "refund"
        }
    }
}
"Example of Card Expiration Warning"
{
    "event": "card_expiration_warning",
    "data": {
        "_id": "589db4311958cb42532f24a3",
        "created_at": "2017-02-10T12:38:11.385Z",
        "updated_at": "2017-02-10T12:38:11.385Z",
        "status": "active",
        "default_source": "589db4331958cb42532f24a4",
        "company_id": "5584018a27b2cf0b1e4f1a6c",
        "user_id": "5584018a27b2cf0b1e4f1a6b",
        "first_name": "Samantha",
        "last_name": "Washington",
        "email": "samwashington@gmail.com",
        "statistics": {
            "total_collected_amount": 5555,
            "successful_transactions": 1,
            "currency": {
                "AUD": {
                    "total_amount": 5555,
                    "count": 1
                }
            }
        },
        "payment_source": {
            "updated_at": "2017-02-10T12:38:11.384Z",
            "vault_token": "f5900584-9ced-4b36-9b3a-5e8976d03d11",
            "address_country": "AU",
            "address_line1": "Suite 660",
            "address_line2": "822 Ruiz Square",
            "address_city": "Sydney",
            "address_postcode": "1111",
            "gateway_id": "56b22bc45a9cb7517bdb1079",
            "card_name": "Samantha Washington",
            "expire_month": 3,
            "expire_year": 2017,
            "card_number_last4": "4444",
            "card_scheme": "mastercard",
            "ref_token": "cus_A5pJfU1O30AJsj",
            "status": "active",
            "created_at": "2017-02-10T12:38:11.125Z",
            "_id": "589db4331958cb42532f24a4",
            "type": "card"
        }
    }
}

Card scheme mapping

Card first n digits Code Name
5610, 560221, 560222, 560223, 560224, 560225 ausbc Australian Bank Card
2014, 2149 diners Diner's Club
36 diners Diner's Club International
3528 - 3589 japcb Japanese Credit Bureau
5018, 5020, 5038, 6304, 6759, 6761 - 6763 maestro Maestro
6304, 6706, 6709, 6771 laser Laser
6334, 6767 solo Solo (Paymentech)
51 - 55, 22 - 27 mastercard MasterCard
6011, 622, 64, 65 discover Discover
34,37 amex American Express
300 - 305, 36, 38, 54, 55, 2014, 2149 diners Diner's Club / Carte Blanche
4026, 417500, 4508, 4844, 4913, 4917 visa Visa Electron
4 visa Visa