Documentation

Introduction

Authentication

API requests authentication is made via HTTP Basic Auth. You have to send an API key as HTTP password, the user field can be left empty. We provide each merchant with the list of API permissions for their account. In the documentation you can see the permission necessary for a specific request next to a key icon. As in:
v1.example.permission
Usage
The example below shows a request to get the list of cards for the merchant identified with an (example) API Key: mer_intg_FR2SUXtrnXgOL2KOHzcMQ9U96lJ3Wxjbr3nuvWD1UDNmyxLh.

In cURL:
curl \
--user :mer_intg_FR2SUXtrnXgOL2KOHzcMQ9U96lJ3Wxjbr3nuvWD1UDNmyxLh \
https://api.straal.com/v1/cards

Responses

The result of your request is indicated by an HTTP status code. Basically all 2xx codes indicate success, and all 4xx codes indicate failure. HTTP status codes descriptions:
200 Request was validated and performed with success
400 Usually indicates bad/malformed request data
402 Related to payments — indicates failure

Error responses

Each response with code 4xx has the same body structure, and it’s constructed like the example below:
{
  "errors": [
    {"code": 10111, "message": "Invalid card number"},
    {"code": 10211, "message": "Invalid customer email"}
  ]
}

Expanding objects

There are various relations between resources existing within Straal API. When retrieving an object using our API, you don't always need all associated objects. For performance and better readability reasons, our API implements the expand parameter, which can be used to retrieve few or all associated objects within one request. To expand multiple objects send a list delimited by ,.

Example request for getting dummy_object
GEThttps://api.straal.com/v1/dummy_objects/g0jk87sc
{
  "id": "g0jk87sc",
  "is_dummy": true,
  "foo": {
    "id": "j5k3jdkwpmz",
    "bar": {
      "id": "j48k502kv"
    }
  }
}
Example request for getting dummy_object with expanded objects
GEThttps://api.straal.com/v1/dummy_objects/g0jk87sc?expand=foo,foo.bar
{
  "id": "g0jk87sc",
  "is_dummy": true,
  "foo": {
    "id": "j5k3jdkwpmz",
    "is_foo_attribute": true,
    "number": 100,
    "bar": {
      "id": "j48k502kv",
      "is_bar_attribute": true,
      "string": "mlk-q",
    }
  }
}

Sorting and filtering

When retrieving lists of objects, you can use filtering and sorting options by sending appropriate URL parameters. To find out which fields are filterable or sortable, refer to API resources descriptions.

Sorting

To specify sorting options, use the sort parameter with a field name, e.g. to sort by "id", add sort=id. You can send multiple field names separated by commas. For multiple sorting options, the rows are ordered according to the first value, then the next value is used to sort the rows which were considered equal in the context of the earlier value, etc. To sort in descending order, prepend - to field name.

Example request with sorting options for dummy_objects:

GEThttps://api.straal.com/v1/dummy_objects?sort=-created_at,name

{
  "data": [
    {
      "id": "g0jk87sc",
      "created_at": 1470239156,
      "name": "B"
    },
    {
      "id": "a4jk83df",
      "created_at": 1470239156,
      "name": "C"
    },
    {
      "id": "an3sdfhj",
      "created_at": 1200034511,
      "name": "A"
    }
  ],
  "page": 1,
  "per_page": 3,
  "total_count": 3
}

Filtering

We support containment operators for simple collections and comparison operators for other field types. Append them to field names with double underscore, like this: /dummy_objects?id__eq=s12345df

Available filter operators:

Description Example usage
eq Equality operator id__eq=s12345df
ne Inequality operator id__ne=s12345df
lt Less than operator created_at__lt=1470239156
gt Greater than operator created_at__gt=1470239156
le Less than or equal operator created_at__le=1470239156
ge Greater than or equal operator created_at__ge=1470239156
in Containment operator

To specify a list of values, use field_name__in parameter multiple times.

id__in=asd123&id__in=123asd
contains Containment operator for collections of simple types errors__contains=70001

Example request with filtering options for dummy_objects:

GEThttps://api.straal.com/v1/dummy_objects?id__eq=g0jk87sc

{
  "data": [
    {
      "id": "g0jk87sc",
      "created_at": 1470239156,
      "name": "B"
    },
  ],
  "page": 1,
  "per_page": 1,
  "total_count": 1
}

API changes

We will not make any breaking changes in the API. However, please note that adding new objects or attributes to existing objects is not considered as breaking change.

Testing resources

You can use the following test credit card numbers and IBANs in your integration environment:

4444444444444448 VISA
4444333322221111 VISA
5555555555554444 MasterCard
5454545454545454 MasterCard
4462030000000000 VISA-subscriptions created with this card will be billed just once, moments after creation. Use it to test billing notifications webhook. For the rest of test cards, subscriptions will be billed according to their plan.
378282246310005 American Express
371449635398431 American Express

Bank account:

PL37109024020000000610000434 Test IBAN. In testing environments, we simulate incoming reconciliations just seconds after creating a transaction. This is helpful for your reconciliations webhook tests. In production, your transactions will have a pending status for 2 to 5 workdays.

The following amounts, when used with card numbers listed above, will result in a failed credit card authorization: 4051, 4005. Any other amounts will be processed successfully.

For bank account transactions (test IBAN listed above), the following amounts will result in authorize_failed reconciliation notification: 4001, 4002, 4003. All other amounts will be processed successfully.

Changelog

2017-07-27

Added reference attribute to transactions.

2017-09-13

Added decline_reason attribute to transactions.

Resources

Transactions

A transaction object represents a real transaction performed on a credit card or a bank account. If the transaction succeeded the authorized attribute is set to true
id
string
Transaction ID
AUTOGENRO
created_at
integer
Timestamp of a transaction creation
AUTOGENRO
amount
integer
required
Transaction amount
RO
currency
string
required
Transaction currency
RO
authorized
boolean
Indicates if a transaction was successfully authorized
captured
boolean
Indicates if a transaction was fully captured
captures
list
List of capture objects performed within a transaction
refunded
boolean
Indicates if a transaction was fully refunded
refunds
list
List of refunds objects performed within a transaction
chargeback
object
Chargeback object, if reported
card
object
Card object on which transaction was performed
bank_account
object
Bank account object on which a transaction was performed
status
string
Status of a transaction, available for bank account transactions
extra_data
object
Additional information about a transaction
reference
string
Your internal transaction reference (has to be unique)
MAXLEN:32UNIQUE
decline_reason
object
Transaction decline reason, if available
For declined transactions additional information is provided in decline_reason attribute.
Sample decline_reason:
{
    "code": 1001,
    "description": "General decline"
}

Create a transaction

This method allows you to perform a transaction on a previously created card object.
POSThttps://api.straal.com/v1/cards/:id/transactions
v1.transactions.create
Sample request for a $9.99 transaction
{
  "amount": 999,
  "currency": "usd",
  "reference": "b138bc50148440ee"
}
Sample response:
{
  "id": "f9g63mazh1wi1",
  "created_at": 1470238921,
  "amount": 999,
  "currency": "usd",
  "authorized": true,
  "captured": true,
  "captures": [
    {
      "id": "qkymdfy2jbui1",
      "created_at": 1470239156,
      "amount": 999
    }
  ],
  "refunded": false,
  "refunds": [],
  "chargeback": null,
  "reference": "b138bc50148440ee",
  "card": {
    "id": "mzivhql5yi9rf",
    "customer": {
      "id": "mhtaqdb4edvrf",
    }
  },
  "decline_reason": null,
  "extra_data": {}
}

Create a transaction with a card

This method allows you to create a card and perform a transaction on it in one request.
POSThttps://api.straal.com/v1/customers/:id/transactions
v1.transactions.create_with_card
Sample request for a $9.99 transaction
{
  "amount": 999,
  "currency": "usd",
  "reference": "b138bc50148440ee",
  "card": {
    "name": "John Smith",
    "number": "4111111111111111",
    "cvv": "123",
    "expiry_month": 11,
    "expiry_year": 2018,
    "origin_ipaddr": "91.17.133.219"
  }
}
Sample response
{
  "id": "f9g63mazh1wi1",
  "created_at": 1470238921,
  "amount": 999,
  "currency": "usd",
  "authorized": true,
  "captured": true,
  "captures": [
    {
      "id": "qkymdfy2jbui1",
      "created_at": 1470239156,
      "amount": 999
    }
  ],
  "refunded": false,
  "refunds": [],
  "chargeback": null,
  "reference": "b138bc50148440ee",
  "card": {
    "id": "mzivhql5yi9rf",
    "created_at": 1467906605,
    "brand": "visa",
    "name": "John Smith",
    "num_bin": "411111",
    "num_last_4": "1111",
    "expiry_month": 11,
    "expiry_year": 2018,
    "origin_ipaddr": "91.17.133.219",
    "customer": {
      "id": "mhtaqdb4edvrf",
    },
  },
  "decline_reason": null,
  "extra_data": {}
}

Create a transaction with a card and a customer

This method allows you to perform a transaction, create a card and a customer in one request.
POSThttps://api.straal.com/v1/transactions
v1.transactions.create_with_card_and_customer
Sample request for a $9.99 transaction
{
  "amount": 999,
  "currency": "usd",
  "reference": "b138bc50148440ee",
  "card": {
    "name": "John Smith",
    "number": "4111111111111111",
    "cvv": "123",
    "expiry_month": 11,
    "expiry_year": 2018,
    "origin_ipaddr": "91.17.133.219",
    "customer": {
      "email": "customer@email.com",
      "reference": "auIj01kcj98lfq",
    }
  }
}
Sample response
{
  "id": "f9g63mazh1wi1",
  "created_at": 1470238921,
  "amount": 999,
  "currency": "usd",
  "authorized": true,
  "captured": true,
  "captures": [
    {
      "id": "qkymdfy2jbui1",
      "created_at": 1470239156,
      "amount": 999
    }
  ],
  "refunded": false,
  "refunds": [],
  "chargeback": null,
  "reference": "b138bc50148440ee",
  "card": {
    "id": "mzivhql5yi9rf",
    "created_at": 1467906605,
    "brand": "visa",
    "name": "John Smith",
    "num_bin": "411111",
    "num_last_4": "1111",
    "expiry_month": 11,
    "expiry_year": 2018,
    "origin_ipaddr": "91.17.133.219",
    "customer": {
      "id": "mhtaqdb4edvrf",
      "created_at": 1467716585,
      "email": "customer@email.com",
      "reference": "auIj01kcj98lfq",
    }
  },
  "decline_reason": null,
  "extra_data": {}
}

Create a transaction for a bank account

This method allows you to perform a transaction on a previously created bank account object. SEPA transactions support only EUR currency.
POSThttps://api.straal.com/v1/bank_accounts/:id/transactions
v1.transactions.create_for_bank_account
Sample request for a €9.99 transaction
{
  "amount": 999,
  "currency": "eur",
  "reference": "b138bc50148440ee"
}
Sample response:
{
  "id": "f9g63mazh1wi1",
  "created_at": 1470238921,
  "amount": 999,
  "currency": "eur",
  "authorized": false,
  "captured": false,
  "captures": [],
  "refunded": false,
  "refunds": [],
  "chargeback": null,
  "reference": "b138bc50148440ee",
  "bank_account": {
    "id": "83ulegbkuvqmf",
    "customer": {
      "id": "mhtaqdb4edvrf",
    }
  },
  "status": "pending",
  "decline_reason": null,
  "extra_data": {}
}

Get a transaction

Returns details of an existing transaction.
GEThttps://api.straal.com/v1/transactions/:id
v1.transactions.get
Sample response:
{
  "id": "5nffaefhmlc6h",
  "created_at": 1472491810,
  "amount": 999,
  "currency": "usd",
  "authorized": true,
  "captured": true,
  "captures": [
    {
      "id": "mkwsfft8hn66y",
      "created_at": 1472473029,
      "amount": 999
    }
  ],
  "refunded": false,
  "refunds": [],
  "chargeback": null,
  "reference": "b138bc50148440ee",
  "card": {
    "id": "5nffaefhmlc6h",
    "customer": {
      "id": "mhtaqdb4edvrf"
    }
  },
  "decline_reason": null,
  "extra_data": {}
}

Get a list of transactions

Returns a list of transactions for the merchant's account.
GEThttps://api.straal.com/v1/transactions
v1.transactions.list
Sample response (limited to 2 objects):
GET /v1/transactions?per_page=2&page=1
{
  "data": [
    {
      "id": "5nffaefhmlc6h",
      "created_at": 1472491810,
      "amount": 999,
      "currency": "usd",
      "authorized": true,
      "captured": true,
      "captures": [
        {
          "id": "mkwsfft8hn66y",
          "created_at": 1472473029,
          "amount": 999
        }
      ],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "card": {
        "id": "5nffaefhmlc6h",
        "customer": {
          "id": "mhtaqdb4edvrf"
        }
      },
      "decline_reason": null,
      "extra_data": {}
    },
    {
      "id": "xdn0ffvrjxf6v",
      "created_at": 1472380727,
      "amount": 1599,
      "currency": "eur",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "1495d2e44a11407b",
      "card": {
        "id": "fqovkf4k5bsbn",
        "customer": {
          "id": "sj7uj23shqf"
        }
      },
      "decline_reason": null,
      "extra_data": {}
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 2
}

Get a list of customer transactions

Returns a list of transactions for a specified customer ID.
GEThttps://api.straal.com/v1/customers/:id/transactions
v1.transactions.customer_list
Sample response (limited to 2 objects):
GET /v1/customers/mhtaqdb4edvrf/transactions?per_page=2&page=1
{
  "data": [
    {
      "id": "5nffaefhmlc6h",
      "created_at": 1472491810,
      "amount": 999,
      "currency": "usd",
      "authorized": true,
      "captured": true,
      "captures": [
        {
          "id": "mkwsfft8hn66y",
          "created_at": 1472473029,
          "amount": 999
        }
      ],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "card": {
        "id": "5nffaefhmlc6h"
      },
      "decline_reason": null,
      "extra_data": {}
    },
    {
      "id": "xdn0ffvrjxf6v",
      "created_at": 1472380727,
      "amount": 1599,
      "currency": "eur",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "1495d2e44a11407b",
      "card": {
        "id": "fqovkf4k5bsbn"
      },
      "decline_reason": null,
      "extra_data": {}
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 2
}

Get transactions for a given card

Returns a list of transactions for a specified card ID.
GEThttps://api.straal.com/v1/cards/:id/transactions
v1.transactions.card_list
Sample response (limited to 2 objects):
GET /v1/cards/5nffaefhmlc6h/transactions?per_page=2&page=1
{
  "data": [
    {
      "id": "5nffaefhmlc6h",
      "created_at": 1472491810,
      "amount": 999,
      "currency": "usd",
      "authorized": true,
      "captured": true,
      "captures": [
        {
          "id": "mkwsfft8hn66y",
          "created_at": 1472473029,
          "amount": 999
        }
      ],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "decline_reason": null,
      "extra_data": {}
    },
    {
      "id": "xdn0ffvrjxf6v",
      "created_at": 1472380727,
      "amount": 1599,
      "currency": "eur",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "1495d2e44a11407b",
      "decline_reason": null,
      "extra_data": {}
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 2
}

Get transactions for a given bank account

Returns a list of transactions for a specified bank account.
GEThttps://api.straal.com/v1/bank_accounts/:id/transactions
v1.transactions.bank_account_list
Sample response (limited to 2 objects):
GET /v1/bank_accounts/83ulegbkuvqmf/transactions?per_page=2&page=1
{
  "data": [
    {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "eur",
      "authorized": false,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "status": "pending",
      "decline_reason": null,
      "extra_data": {}
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 1
}

Get transactions for a given subscription

Returns a list of transactions for a specified subscription ID.
GEThttps://api.straal.com/v1/subscriptions/:id/transactions
v1.transactions.subscription_list
Sample response (limited to 2 objects):
GET /v1/subscriptions/m5lwrskt18r4f/transactions?per_page=2&page=1
{
  "data": [
    {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "usd",
      "authorized": true,
      "captured": true,
      "captures": [
        {
          "id": "mkwsfft8hn66y",
          "created_at": 1472473029,
          "amount": 999
        }
      ],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "card": {
        "id": "5nffaefhmlc6h",
        "customer": {
          "id": "mhtaqdb4edvrf"
        }
      },
      "decline_reason": null,
      "extra_data": {}
    },
    {
      "id": "xdn0ffvrjxf6v",
      "created_at": 1472380727,
      "amount": 999,
      "currency": "usd",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "1495d2e44a11407b",
      "card": {
        "id": "5nffaefhmlc6h",
        "customer": {
          "id": "mhtaqdb4edvrf"
        }
      },
      "decline_reason": null,
      "extra_data": {}
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 2
}

Refunds

The refund object represents a real refund operation performed on a credit card.
id
string
Refund ID
AUTOGENRO
created_at
integer
Timestamp of refund creation
AUTOGENRO
amount
integer
Amount to refund. If not set, full refund will be performed
status
string
Refund status. It may have one of the following values: succeeded, pending or failed
RO
extra_data
object
Additional information about refund. It might be useful to store e.g. information about refund reason

Create a full refund

This method allows you to perform a refund on a previously created transaction. The refund method returns a transaction object that was being refunded. If the full refund succeeded, the refunded attribute on the transaction object is set to true.
POSThttps://api.straal.com/v1/transactions/:id/refund
v1.transactions.refund
Sample request for full refund with extra_data.
{
  "extra_data": {
    "reason": "cancellation"
  }
}
Sample response:
{
  "id": "f9g63mazh1wi1",
  "created_at": 1470238921,
  "amount": 999,
  "currency": "usd",
  "authorized": true,
  "captured": true,
  "captures": [
    {
      "id": "qkymdfy2jbui1",
    }
  ],
  "refunded": true,
  "refunds": [
    {
      "id": "cz8tteizwf0bv",
      "created_at": 1487694077,
      "amount": 999,
      "status": "succeeded",
      "extra_data": {
        "reason": "cancellation"
      },
    }
  ],
  "chargeback": null,
  "reference": "b138bc50148440ee",
  "card": {
    "id": "mzivhql5yi9rf",
    "customer": {
      "id": "mhtaqdb4edvrf"
    },
  },
  "decline_reason": null,
  "extra_data": {}
}
It is also possible to make a full refund without extra_data by just sending a POST request with an empty body.

Create a partial refund

To make a partial refund you have to use the same method as for a full refund. The request body needs to contain the amount that should be credited.
It is possible to perform more than one partial refund per transaction, as long as their sum does not exceed the original transaction amount. If the sum of partial refunds is equal to the amount of the transaction, the transaction attribute refunded is set to true.
POSThttps://api.straal.com/v1/transactions/:id/refund
v1.transactions.refund
Sample request for a partial refund:
{
  "amount": 499
}
Sample response:
{
  "id": "f9g63mazh1wi1",
  "created_at": 1470238921,
  "amount": 999,
  "currency": "usd",
  "authorized": true,
  "captured": true,
  "captures": [
    {
      "id": "qkymdfy2jbui1",
    }
  ],
  "refunded": false,
  "refunds": [
    {
      "id": "cz8tteizwf0bv",
      "created_at": 1487694077,
      "amount": 499,
      "status": "succeeded",
      "extra_data": {},
    }
  ],
  "chargeback": null,
  "reference": "b138bc50148440ee",
  "card": {
    "id": "mzivhql5yi9rf",
    "customer": {
      "id": "mhtaqdb4edvrf"
    },
  },
  "decline_reason": null,
  "extra_data": {}
}

Cards

Card is an object which represents a credit card and its ID acts as a token which can be used to perform further transactions.
id
string
Card object ID
AUTOGENRO
created_at
integer
Timestamp of object creation
AUTOGENRO
brand
string
Credit card brand
name
string
required
Cardholder name on card
number
string
required
Credit card number, required on card creation
POST ONLY
num_bin
string
6 digits Card BIN number (based on posted number)
AUTOGENRO
num_last_4
string
Last 4 digits of card number (based on posted number)
AUTOGENRO
cvv
string
Card security code, used only on card creation
POST ONLY
expiry_month
int
required
Card expiration month (format: 1-12)
expiry_year
int
required
Card expiration year (in YYYY format)
origin_ipaddr
string
required conditionally
IP address from which the card was created. Required only if request is sent from your backend
RO
customer
object
Credit card owner
EXPANDABLE

Create a card

Creates a card for a specified customer ID.
POSThttps://api.straal.com/v1/customers/:customer_id/cards
v1.cards.create
Sample request:
{
  "name": "John Smith",
  "number": "4111111111111111",
  "cvv": "123",
  "expiry_month": 11,
  "expiry_year": 2018,
  "origin_ipaddr": "91.17.133.219"
}
Sample response:
{
  "id": "mzivhql5yi9rf",
  "created_at": 1467906605,
  "brand": "visa",
  "name": "John Smith",
  "num_bin": "411111",
  "num_last_4": "1111",
  "expiry_month": 11,
  "expiry_year": 2018,
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "id": "mbrudb30nt9rf",
  }
}

Create a card with a customer

POSThttps://api.straal.com/v1/cards
v1.cards.create_with_customer
Sample request:
{
  "name": "John Smith",
  "number": "4111111111111111",
  "cvv": "123",
  "expiry_month": 11,
  "expiry_year": 2018,
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "email": "customer@email.com",
    "reference": "auIj01kcj98lfq",
  }
}
Sample response:
{
  "id": "mzivhql5yi9rf",
  "created_at": 1467906605,
  "brand": "visa",
  "name": "John Smith",
  "num_bin": "411111",
  "num_last_4": "1111",
  "expiry_month": 11,
  "expiry_year": 2018,
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "id": "mhtaqdb4edvrf",
    "created_at": 1467716585,
    "email": "customer@email.com",
    "reference": "auIj01kcj98lfq",
  }
}

Get a card

Returns information of a specified card.
GEThttps://api.straal.com/v1/cards/:id
v1.cards.get
Sample response:
{
  "id": "mzivhql5yi9rf",
  "created_at": 1467906605,
  "brand": "visa",
  "name": "John Smith",
  "num_bin": "411111",
  "num_last_4": "1111",
  "expiry_month": 11,
  "expiry_year": 2018,
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "id": "mbrudb30nt9rf"
  }
}

Get the card list

Returns a list of cards for the merchant's account.
GEThttps://api.straal.com/v1/cards
v1.cards.list
Sample response (limited to 3 objects):
GET /v1/cards?per_page=3&page=1
{
  "data": [
      {
        "id": "sq5g33mh9jf9f",
        "created_at": 1470090665,
        "brand": "visa",
        "name": "John Smith",
        "num_bin": "411111",
        "num_last_4": "1111",
        "expiry_month": 10,
        "expiry_year": 2016,
        "origin_ipaddr": "123.10.11.12",
        "customer": {
          "id": "bq75z9dhfut5k"
        }
      },
      {
        "id": "s9b7f7cqsmzd1",
        "created_at": 1474548758,
        "brand": "visa",
        "name": "Alan Moore",
        "num_bin": "424242",
        "num_last_4": "4242",
        "expiry_month": 6,
        "expiry_year": 2018,
        "origin_ipaddr": "11.99.98.97",
        "customer": {
          "id": "k9ibjzfdaoi5c"
        }
      },
      {
        "id": "k3n2btvbdrnsq",
        "created_at": 1474548758,
        "brand": "mastercard",
        "name": "George Miller",
        "num_bin": "555555",
        "num_last_4": "4444",
        "expiry_month": 1,
        "expiry_year": 2019,
        "origin_ipaddr": "22.33.44.100",
        "customer": {
          "id": "00khkb5c0q75b"
        }
      }
  ],
  "page": 1,
  "per_page": 3,
  "total_count": 5
}

Get customer's cards

Returns a list of cards assigned to a specified customer ID.
GEThttps://api.straal.com/v1/customers/:id/cards
v1.cards.customer_list
Sample response (limited to 3 objects):
GET /v1/customers/znhibktfny95i/cards?per_page=3&page=1
{
  "data": [
      {
        "id": "sq5g33mh9jf9f",
        "created_at": 1470090665,
        "brand": "visa",
        "name": "George Smith",
        "num_bin": "411111",
        "num_last_4": "1111",
        "expiry_month": 10,
        "expiry_year": 2016,
        "origin_ipaddr": "123.10.11.12",
      },
      {
        "id": "k3n2btvbdrnsq",
        "created_at": 1474548758,
        "brand": "mastercard",
        "name": "George Smith",
        "num_bin": "555555",
        "num_last_4": "4444",
        "expiry_month": 1,
        "expiry_year": 2019,
        "origin_ipaddr": "22.33.44.100",
      }
  ],
  "page": 1,
  "per_page": 3,
  "total_count": 2
}

Bank Accounts

Bank account can be used to perform SEPA Direct Debit transactions.
id
string
Bank account object ID
AUTOGENRO
created_at
integer
Timestamp of object creation
AUTOGENRO
name
string
required
Bank account holder name
iban
string
required
The International Bank Account Number
bic
string
required
The Business Identifier Code
mandate_id
string
ID of mandate created for bank account object
AUTOGENRO
origin_ipaddr
string
required conditionally
IP address from which the bank account was created. Required only if request is sent from your backend
RO
customer
object
Bank account owner
EXPANDABLE

Create a bank account

Creates a bank account for a specified customer.
POSThttps://api.straal.com/v1/customers/:customer_id/bank_accounts
v1.bank_accounts.create
Sample request:
{
  "name": "John Smith",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "origin_ipaddr": "91.17.133.219",
}
Sample response:
{
  "id": "83ulegbkuvqmf",
  "created_at": 1487251609,
  "name": "John Smith",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "mandate_id": "a84764a157a840daabbc22136ab2b067",
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "id": "mbrudb30nt9rf",
  }
}

Create a bank account with a customer

This method allows you to create a bank account and a customer.
POSThttps://api.straal.com/v1/bank_accounts
v1.bank_accounts.create_with_customer
Sample request:
{
  "name": "John Smith",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "email": "customer@email.com",
    "reference": "auIj01kcj98lfq",
  }
}
Sample response:
{
  "id": "83ulegbkuvqmf",
  "created_at": 1487251609,
  "name": "John Smith",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "mandate_id": "a84764a157a840daabbc22136ab2b067",
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "id": "q12l8eww2vymk",
    "created_at": 1487251608,
    "email": "customer@email.com",
    "reference": "auIj01kcj98lfq",
  }
}

Get a bank account

Returns information about a bank account with a specified ID.
GEThttps://api.straal.com/v1/bank_accounts/:id
v1.bank_accounts.get
Sample response:
{
  "id": "83ulegbkuvqmf",
  "created_at": 1487251609,
  "name": "John Smith",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "mandate_id": "a84764a157a840daabbc22136ab2b067",
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "id": "mbrudb30nt9rf",
  }
}

Get the bank account list

Returns a list of bank accounts for the merchant's account.
GEThttps://api.straal.com/v1/bank_accounts
v1.bank_accounts.list
Sample response (limited to 3 objects):
GET /v1/bank_accounts?per_page=3&page=1
{
  "data": [
      {
        "id": "83ulegbkuvqmf",
        "created_at": 1487251609,
        "name": "John Smith",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "mandate_id": "a84764a157a840daabbc22136ab2b067",
        "origin_ipaddr": "91.17.133.219",
        "customer": {
          "id": "mbrudb30nt9rf",
        }
      },
      {
        "id": "s9b7f7cqsmzd1",
        "created_at": 1474548758,
        "name": "Alan Moore",
        "iban": "DE09100100101234567890",
        "bic": "PBNKDEFFXXX",
        "mandate_id": "86d1def33a3c4972b72b0f3ffbeb646c",
        "origin_ipaddr": "11.99.98.97",
        "customer": {
          "id": "k9ibjzfdaoi5c",
        }
      },
      {
        "id": "k3n2btvbdrnsq",
        "created_at": 1474548758,
        "name": "George Miller",
        "iban": "DE79850503003100180568",
        "bic": "OSDDDE81",
        "mandate_id": "84905ef30e33414cbd49c5282ffc01b6",
        "origin_ipaddr": "22.33.44.100",
        "customer": {
          "id": "00khkb5c0q75b",
        }
      }
  ],
  "page": 1,
  "per_page": 3,
  "total_count": 5
}

Get a customer's bank account list

Returns a list of transactions for the specified customer ID.
GEThttps://api.straal.com/v1/customers/:id/bank_accounts
v1.bank_accounts.customer_list
Sample response (limited to 3 objects):
GET /v1/customers/mbrudb30nt9rf/bank_accounts?per_page=3&page=1
{
  "data": [
      {
        "id": "83ulegbkuvqmf",
        "created_at": 1487251609,
        "name": "John Smith",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "mandate_id": "a84764a157a840daabbc22136ab2b067",
        "origin_ipaddr": "91.17.133.219",
      },
      {
        "id": "s9b7f7cqsmzd1",
        "created_at": 1474548758,
        "name": "John Smith",
        "iban": "DE09100100101234567890",
        "bic": "PBNKDEFFXXX",
        "mandate_id": "86d1def33a3c4972b72b0f3ffbeb646c",
        "origin_ipaddr": "11.99.98.97",
      }
  ],
  "page": 1,
  "per_page": 3,
  "total_count": 2
}

Customers

Customer object represents your application/site user.
id
string
Customer object ID
AUTOGENRO
created_at
integer
Timestamp of object creation
AUTOGENRO
email
string
required
Customer email address
reference
string
Your internal customer reference (Integers are accepted but will be converted to string)
MAXLEN:32

Create a customer

POSThttps://api.straal.com/v1/customers
v1.customers.create
Sample request:
{
  "email": "customer@email.com", 
  "reference": "auIj01kcj98lfq"
}
Sample response:
{
  "id": "mhtaqdb4edvrf", 
  "created_at": 146771658, 
  "email": "customer@email.com", 
  "reference": "auIj01kcj98lfq"
}

Get a customer

Returns a customer for a specified ID.
GEThttps://api.straal.com/v1/customers/:id
v1.customers.get
Sample response:
{
  "id": "mhtaqdb4edvrf",
  "created_at": 1467716585,
  "email": "customer@email.com",
  "reference": "auIj01kcj98lfq",
}

Get the customer list

Returns a list of customers for the merchant's account.
GEThttps://api.straal.com/v1/customers
v1.customers.list
Sample response (limited to 2 objects):
GET /v1/customers?per_page=2&page=1
{
  "data": [
    {
      "id": "k9ibjzfdaoi5c",
      "created_at": 1451655351,
      "email": "customer@email.com",
      "reference": "81lau82pnneb8",
    },
    {
      "id": "mhtaqdb4edvrf",
      "created_at": 1467716585,
      "email": "shopper@email.com",
      "reference": "auIj01kcj98lfq",
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 3
}

Subscriptions

Subscription object allows you to automatically charge a user for a specified amount in a recurring manner. The amount depends on the plan associated with the subscription. Subscription requires a payment source, i.e. a card or a bank account.
id
string
Subscription object ID
AUTOGENRO
created_at
integer
Timestamp of object creation
AUTOGENRO
current_period_start
integer
-
AUTOGENRO
current_period_end
integer
-
AUTOGENRO
active
boolean
Indicates if subscription is active
cancelled_at
integer
Cancellation timestamp
plan_id
string
required
ID of plan object
POST ONLY
card
object
Card associated with subscription
EXPANDABLE
bank_account
object
Bank account associated with subscription
EXPANDABLE
plan
object
Plan associated with subscription
EXPANDABLE
extra_data
object
Optional additional information about subscription
straal_custom_data
object
Information relating to custom Straal integrations
RO

Create a subscription

Creates a subscription for a specified card ID. You can use this method multiple times to create additional subscriptions for one card.
POSThttps://api.straal.com/v1/cards/:id/subscriptions
v1.subscriptions.create
Sample request:
{
  "plan_id": "mcn15j2hwhq4f"
}
Sample response:
{
  "id": "m5lwrskt18r4f",
  "created_at": 1468577492,
  "active": true,
  "cancelled_at": null,
  "current_period_start": 1468577492,
  "current_period_end": 1471169492,
  "card": {
    "id": "mru196faf8r4f",
    "customer": {
      "id": "mj3mg7w3w8r4f",
    }
  },
  "plan": {
    "id": "mcn15j2hwhq4f",
  },
  "extra_data": {},
  "straal_custom_data": {}
}

Create a subscription with a card and a customer

This method allows creating a subscription and a customer using a single request by sending both required objects (card and customer). The card created in this request automatically becomes active, which in practice means that all subscription transactions will be performed using this card.
Notes:
- card and customer objects are required while sending a request to this URL
- when using this method, the credit card needs to be authorized, so Verification Authorization will be made.
POSThttps://api.straal.com/v1/subscriptions
v1.subscriptions.create_with_card_and_customer
Sample request:
{
  "plan_id": "mcn15j2hwhq4f",
  "card": {
    "name": "Samwell Gordon",
    "number": "4444333322221111",
    "cvv": "789",
    "expiry_month": 7,
    "expiry_year": 2019,
    "origin_ipaddr": "54.4.125.235",
    "customer": {
      "email": "customer@email.com",
      "reference": 7459320801
    }
  }
}
Sample response:
{
  "id": "m5lwrskt18r4f",
  "created_at": 1468577492,
  "active": true,
  "cancelled_at": null,
  "current_period_start": 1468577492,
  "current_period_end": 1471169492,
  "card": {
    "id": "mru196faf8r4f",
    "created_at": 1468577403,
    "brand": "visa",
    "name": "Samwell Gordon",
    "num_bin": "444433",
    "num_last_4": "1111",
    "expiry_month": 7,
    "expiry_year": 2019,
    "origin_ipaddr": "54.4.125.235",
    "customer": {
      "id": "mj3mg7w3w8r4f",
      "created_at": 1468577694,
      "email": "customer@email.com",
      "reference": "7459320801",
    }
  },
  "plan": {
    "id": "mcn15j2hwhq4f",
  },
  "extra_data": {},
  "straal_custom_data": {}
}

Create a subscription for a given bank account

You can create subscriptions for existing bank accounts using this method. Only plans which have EUR as declared currency are supported with bank accounts.
POSThttps://api.straal.com/v1/bank_accounts/:id/subscriptions
v1.subscriptions.create_for_bank_account
Sample request:
{
  "plan_id": "mcn15j2hwhq4f"
}
Sample response:
{
  "id": "bo10e8kfc8pmc",
  "created_at": 1487258578,
  "active": true,
  "cancelled_at": null,
  "current_period_start": 1487258583,
  "current_period_end": 1489850578,
  "bank_account": {
    "id": "83ulegbkuvqmf",
    "customer": {
      "id": "q12l8eww2vymk",
    }
  },
  "plan": {
    "id": "mcn15j2hwhq4f",
  },
  "extra_data": {},
  "straal_custom_data": {}
}

Get a subscription

Returns details of an existing subscription.
GEThttps://api.straal.com/v1/subscriptions/:id
v1.subscriptions.get
Sample response:
{
  "id": "m5lwrskt18r4f",
  "created_at": 1468577492,
  "active": true,
  "cancelled_at": null,
  "current_period_start": 1468577492,
  "current_period_end": 1471169492,
  "card": {
    "id": "mru196faf8r4f",
    "customer": {
      "id": "mj3mg7w3w8r4f",
    }
  },
  "plan": {
    "id": "mcn15j2hwhq4f",
  },
  "extra_data": {},
  "straal_custom_data": {}
}

Get the subscription list

Returns a list of subscriptions for the merchant's account.
GEThttps://api.straal.com/v1/subscriptions
v1.subscriptions.list
Sample response (limited to 2 objects):
GET /v1/subscriptions?per_page=2&page=1
{
  "data": [
    {
      "id": "m5lwrskt18r4f",
      "created_at": 1468577492,
      "active": true,
      "cancelled_at": null,
      "current_period_start": 1468577492,
      "current_period_end": 1471169492,
      "card": {
        "id": "mru196faf8r4f",
        "customer": {
          "id": "mj3mg7w3w8r4f"
        }
      },
      "plan": {
        "id": "mcn15j2hwhq4f"
      },
      "extra_data": {},
      "straal_custom_data": {}
    },
    {
      "id": "bo10e8kfc8pmc",
      "created_at": 1487258578,
      "active": true,
      "cancelled_at": null,
      "current_period_start": 1487258583,
      "current_period_end": 1489850578,
      "bank_account": {
        "id": "83ulegbkuvqmf",
        "customer": {
          "id": "q12l8eww2vymk"
        }
      },
      "plan": {
        "id": "mcn15j2hwhq4f"
      },
      "extra_data": {}
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 3
}

Get the subscription list for a given customer

Returns a list of subscriptions assigned to a specified customer ID.
GEThttps://api.straal.com/v1/customers/:id/subscriptions
v1.subscriptions.customer_list
Sample response (limited to 3 objects):
GET /v1/customers/:id/subscriptions?per_page=3&page=1
{
  "data": [
    {
      "id": "439to9r0ezfwq",
      "created_at": 1497258894,
      "active": true,
      "cancelled_at": null,
      "current_period_start": 1497950093,
      "current_period_end": 1500542093,
      "card": {"id": "ehgl79c6xm431"},
      "plan": {
        "id": "v0fbvbm6m3fii"
      },
      "extra_data": {},
      "straal_custom_data": {}
    }
  ],
  "page": 1,
  "per_page": 3,
  "total_count": 1
}

Get the subscription list for a given card

Returns a list of subscriptions assigned to a specified card ID.
GEThttps://api.straal.com/v1/cards/:id/subscriptions
v1.subscriptions.card_list
Sample response (limited to 3 objects):
GET /v1/cards/:id/subscriptions?per_page=3&page=1
{
  "data": [
    {
      "id": "r3jo8a6rga9t7",
      "created_at": 1497258894,
      "active": true,
      "cancelled_at": null,
      "current_period_start": 1497950093,
      "current_period_end": 1500542093,
      "plan": {
        "id": "amnbrf6htplmt"
      },
      "extra_data": {},
      "straal_custom_data": {}
    }
  ],
  "page": 1,
  "per_page": 3,
  "total_count": 1
}

Cancel a subscription

Cancels an existing subscription. Use with caution: you cannot reinstate a cancelled subscription. You will have to create a new one instead.
POSThttps://api.straal.com/v1/subscriptions/:id/cancel
v1.subscriptions.cancel
Sample response:
{
  "id": "m5lwrskt18r4f",
  "created_at": 1468577492,
  "active": false,
  "cancelled_at": 1488214269,
  "current_period_start": 1468577492,
  "current_period_end": 1471169492,
  "card": {
    "id": "mru196faf8r4f",
    "customer": {
      "id": "mj3mg7w3w8r4f",
    }
  },
  "plan": {
    "id": "mcn15j2hwhq4f",
  },
  "extra_data": {},
  "straal_custom_data": {}
}

CSRs (Create Subscription Requests)

Create Subscription Request object stores data related to subscription creation: card or bank account, transactions, plan and, if the request succeeded, also subscription. We create CSR objects automatically for correctly formed POST requests to subscription endpoints.
id
string
CSR ID
AUTOGENROFILTERABLE
created_at
integer
Timestamp of CSR object creation
AUTOGENROSORTABLEFILTERABLE
card
object
Card object to charge subscription fees
RO
bank_account
object
Bank account object to charge subscription fees
RO
errors
list
List of errors related to this CSR
RO
antifraud_response
object
Information from the antifraud system
RO
transactions
list
List of transaction objects related to this CSR
RO
subscription
object
Subscription object created by this CSR
RO

Get a CSR

Returns details of a CSR.
GEThttps://api.straal.com/v1/csrs/:id
v1.csrs.get
Sample response:
{
  "antifraud_response": {
    "advice": "accept"
  },
  "bank_account": null,
  "card": {
    "customer": {
        "id": "ear228iqwtkaa"
    },
    "id": "khaete0qbtwav"
  },
  "created_at": 1492785759,
  "errors": [],
  "id": "a1w9e3nqstkaw",
  "plan": {
    "id": "an7der6qztkaw"
  },
  "subscription": {
    "id": "kllcsanqwteat",
    "plan": {
      "id": "an7der6qztkaw"
    }
  },
  "transactions": [
    {
      "captures": [
        {
          "id": "wlciak9q5tear"
        }
      ],
      "id": "kzfmtaoqwteak",
      "refunds": [
        {
          "id": "ltqat1ecykkaw"
        }
      ]
    }
  ]
}

Get the CSR list

Returns the list of CSRs for the merchant's account.
GEThttps://api.straal.com/v1/csrs
v1.csrs.list
Sample response (limited to 2 objects):
GET /v1/csrs?per_page=2&page=1
{
  "data": [
    {
      "antifraud_response": {
        "advice": "accept"
      },
      "bank_account": null,
      "card": {
        "customer": {
            "id": "ear228iqwtkaa"
        },
        "id": "khaete0qbtwav"
      },
      "created_at": 1492785759,
      "errors": [],
      "id": "a1w9e3nqstkaw",
      "plan": {
        "id": "an7der6qztkaw"
      },
      "subscription": {
        "id": "kllcsanqwteat",
        "plan": {
          "id": "an7der6qztkaw"
        }
      },
      "transactions": [
        {
          "captures": [
            {
              "id": "wlciak9q5tear"
            }
          ],
          "id": "kzfmtaoqwteak",
          "refunds": [
            {
              "id": "ltqat1ecykkaw"
            }
          ]
        }
      ]
    },
    {
      "antifraud_response": {
        "advice": "refuse"
      },
      "bank_account": null,
      "card": {
        "customer": {
            "id": "qfdafg43sdfgh"
        },
        "id": "bvzxadfjk34df"
      },
      "created_at": 1492784444,
      "errors": [
        {"code": 70001, "message": "Dropped by antifraud"},
      ],
      "id": "a345fghjsvsa",
      "plan": {
        "id": "vcxea35tsdfa"
      },
      "subscription": null,
      "transactions": []
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 2
}

Plans

Plan defines how often and what amount will be taken off customer's account during subscription lifetime.
id
string
Plan object ID
AUTOGENRO
created_at
integer
Timestamp of object creation
AUTOGENRO
name
string
Optional plan name
MAXLEN:128
amount
integer
required
Defines amount of recurring transactions
currency
string
required
Defines currency of recurring transactions
trial_days
integer
Trial period
step_type
string
required
One of day, month, year
step_value
integer
required

Create a plan

POSThttps://api.straal.com/v1/plans
v1.plans.create
Sample request for creating $19.99 monthly plan with a 7-day trial period.
{
  "name": "Regular monthly $19.99", 
  "amount": 1999, 
  "currency": "usd", 
  "trial_days": 7, 
  "step_type": "month", 
  "step_value": 1
}
Response:
{
  "id": "mj501ot7vxwsf", 
  "created_at": 1470068395, 
  "name": "Regular monthly $19.99", 
  "amount": 1999, 
  "currency": "usd", 
  "trial_days": 7, 
  "step_type": "month", 
  "step_value": 1
}

Get a plan

Returns details of an existing plan.
GEThttps://api.straal.com/v1/plans/:id
v1.plans.get
Sample response:
{
  "id": "mj501ot7vxwsf",
  "created_at": 1470068395,
  "name": "Regular monthly $19.99",
  "amount": 1999,
  "currency": "usd",
  "trial_days": 7,
  "step_type": "month",
  "step_value": 1
}

Get the list of plans

Returns a list of plans for the merchant's account.
GEThttps://api.straal.com/v1/plans
v1.plans.list
Sample response (limited to 2 objects):
GET /v1/plans?per_page=2&page=1
{
  "data": [
    {
      "id": "mj501ot7vxwsf",
      "created_at": 1470068395,
      "name": "Regular monthly $19.99",
      "amount": 1999,
      "currency": "usd",
      "trial_days": 7,
      "step_type": "month",
      "step_value": 1
    },
    {
      "id": "8o38exhmhtabr",
      "created_at": 1487591767,
      "name": "Premium monthly $59.99",
      "amount": 5999,
      "currency": "usd",
      "trial_days": 7,
      "step_type": "month",
      "step_value": 1
    }
  ],
  "page": 1,
  "per_page": 2,
  "total_count": 3
}

CryptKeys

CryptKey is a special object that allows you to send encrypted data directly to our API endpoint without needing to authorize using APIKey. This can be useful in various scenarios, such as making a request from mobile or web applications where you can't expose the APIKey. CryptKey can be used to make only a single request, and can be generated only with one permission which reflects specific API request. Because the data is not sent through your back end, you have to keep in mind fewer PCI-compliance requirements.
id
string
Card object ID
AUTOGENRO
created_at
integer
Timestamp of object creation
AUTOGENRO
key
string
Actual key which will be used to encrypt data
AUTOGENRO
ttl
integer
Key expiration time (in seconds)
AUTOGENRO
permission
string
required
Valid request permission string
RO

Usage

Every request encrypted with CryptKey should be sent to special endpoint:
GEThttps://api.straal.com/v1/encrypted
Since Straal API is designed around REST principles, there are some endpoints that require putting parent object ID in request path. For security reasons, those IDs should not be exposed in your application front end code, so you have to provide them during CryptKey creation request.

Example

Normally when you want to create a card, you would put customer_id in request path. Since you can't do it while sending encrypted data, you have to provide it in create cryptkey request payload. Sample request:
{
  "permission": "v1.cards.create",
  "customer_id": "mzivhql5yi9rf"
}
Now you have to construct the proper payload for create a card method, encrypt it using newly created CryptKey and send the data to /v1/encrypted endpoint. By completing these actions you will create a card for a customer with ID mzivhql5yi9rf.

Create a CryptKey

A request for creating CryptKey has to be authorized by APIKey. It means that you have to make it from your application backend.
POSThttps://api.straal.com/v1/cryptkeys
v1.cryptkeys.create
Sample request:
{
  "permission": "v1.cards.create"
}
Sample response (key attribute is shortened):
{
  "id": "70xfzmynzgkih", 
  "created_at": 1470302857, 
  "key": "06c5fbc1a9800003ba(...)", 
  "permission": "v1.cards.create", 
  "ttl": 600
}

Straal.js

Overview

Straal.js is a helper library to make it easier to make API requests directly from merchant's website. It utilizes client-side encryption and sends data over HTTPS to make secure transactions.

Usage

In order to perform a transaction request directly from your website you have to do the following:

1. Create a CryptKey on your application backend.
2. Pass the generated CryptKey to frontend part of your site (via request or templating).
3. Pass CryptKey into Straal.js client code.

Notifications

Overview

Straal can notify your backend about certain events. For example, when we charge customer subscription, or after a transaction performed by your user from a mobile device. The notification is a regular HTTP request with JSON-formatted data.

Request finished

Event name: request_finished

When configured, this notification is sent each time when a transaction-related request is made. It contains the entire response body along with some extra information. Configuring this notification is highly recommended for clients sending encrypted requests directly from their website or a mobile device.

Sample notification:
{
  "event": "request_finished",
  "data": {
    "path": "/v1/cards/mzivhql5yi9rf/transactions",
    "permission": "v1.transactions.create",
    "auth_method": "cryptkey",
    "cryptkey": {
      "id": "70xfzmynzgkih"
    },
    "request_id": "0e04ead77926441c9369f1932ddd13c8",
    "response": {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "usd",
      "authorized": true,
      "captured": true,
      "captures": [
        {
          "id": "qkymdfy2jbui1",
          "created_at": 1470239156,
          "amount": 999
        }
      ],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "card": {
        "id": "mzivhql5yi9rf",
        "customer": {
          "id": "mhtaqdb4edvrf",
        }
      },
      "decline_reason": null,
      "extra_data": {}
    }
  }
}

Reconciliations

These notifications are sent only for SEPA Direct Debit transactions.

Authorized

Event name: authorized

This notification is sent when a SEPA Direct Debit transaction is settled.

Sample notification:
{
  "event": "authorized",
  "data": {
    "transaction": {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "eur",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "bank_account": {
        "id": "83ulegbkuvqmf",
        "customer": {
          "id": "mhtaqdb4edvrf",
        }
      },
      "status": "succeeded",
      "decline_reason": null,
      "extra_data": {}
    },
    "timestamp": 1487440567
  }
}

Authorize failed

Event name: authorize_failed

This notification is sent when a SEPA Direct Debit transaction is declined.

Sample notification:
{
  "event": "authorize_failed",
  "data": {
    "transaction": {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "eur",
      "authorized": false,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "bank_account": {
        "id": "83ulegbkuvqmf",
        "customer": {
          "id": "mhtaqdb4edvrf",
        }
      },
      "status": "failed",
      "decline_reason": {
        "code": 1001,
        "description": "General decline"
      },
      "extra_data": {}
    },
    "timestamp": 1487440567
  }
}

Refund succeeded

Event name: refund_succeeded

This notification is sent when a SEPA Direct Debit transaction refund is settled.

Sample notification for a partial refund:
{
  "event": "refund_succeeded",
  "data": {
    "transaction": {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "eur",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [
        {
          "id": "mkwsfft8hn66y",
          "created_at": 1472473029,
          "amount": 900,
          "status": "succeeded",
          "extra_data": {}
        }
      ],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "bank_account": {
        "id": "83ulegbkuvqmf",
        "customer": {
          "id": "mhtaqdb4edvrf",
        }
      },
      "status": "partially_refunded",
      "decline_reason": null,
      "extra_data": {}
    },
    "timestamp": 1487440567
  }
}

Sample notification for a full refund:
{
  "event": "refund_succeeded",
  "data": {
    "transaction": {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "eur",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": true,
      "refunds": [
        {
          "id": "mkwsfft8hn66y",
          "created_at": 1472473029,
          "amount": 999,
          "status": "succeeded",
          "extra_data": {}
        }
      ],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "bank_account": {
        "id": "83ulegbkuvqmf",
        "customer": {
          "id": "mhtaqdb4edvrf",
        }
      },
      "status": "refunded",
      "decline_reason": null,
      "extra_data": {}
    },
    "timestamp": 1487440567
  }
}

Refund failed

Event name: refund_failed

This notification is sent when a SEPA Direct Debit transaction refund is declined.

Sample notification:
{
  "event": "refund_failed",
  "data": {
    "transaction": {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "eur",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [
        {
          "id": "mkwsfft8hn66y",
          "created_at": 1472473029,
          "amount": 999,
          "status": "failed",
          "extra_data": {}
        }
      ],
      "chargeback": null,
      "reference": "b138bc50148440ee",
      "bank_account": {
        "id": "83ulegbkuvqmf",
        "customer": {
          "id": "mhtaqdb4edvrf",
        }
      },
      "status": "succeeded",
      "decline_reason": null,
      "extra_data": {}
    },
    "timestamp": 1487440567
  }
}

Chargeback

Event name: chargeback

This notification is sent when a SEPA Direct Debit transaction is charged back.

Sample notification:
{
  "event": "chargeback",
  "data": {
    "transaction": {
      "id": "f9g63mazh1wi1",
      "created_at": 1470238921,
      "amount": 999,
      "currency": "eur",
      "authorized": true,
      "captured": false,
      "captures": [],
      "refunded": false,
      "refunds": [],
      "chargeback": {
        "id": "gnranrehp3gl6",
        "effective_date": 1486684800,
        "reason_code": "MD06",
        "reason_description": "Disputed authorised transaction"
      },
      "reference": "b138bc50148440ee",
      "bank_account": {
        "id": "83ulegbkuvqmf",
        "customer": {
          "id": "mhtaqdb4edvrf",
        }
      },
      "status": "chargeback",
      "decline_reason": null,
      "extra_data": {}
    },
    "timestamp": 1487440567
  }
}

Subscription billing

Recurring payment succeeded

Event name: recurring_payment_succeeded

This notification is sent when a recurring payment (i.e. billing according to the subscription's plan) succeeds.

Sample notification:
{
     "event": "recurring_payment_succeeded",
     "data": {
         "transaction": {
             "id": "f9g63mazh1wi1",
             "created_at": 1470238921,
             "amount": 2000,
             "currency": "usd",
             "authorized": true,
             "captured": true,
             "refunded": false,
             "captures": [{
                 "id": "qkymdfy2jbui1",
                 "created_at": 1470239156,
                 "amount": 2000
             }],
             "refunds": [],
             "card": {
                 "id": "mzivhql5yi9rf",
                 "customer": {
                     "id": "mhtaqdb4edvrf"
                 }
             },
             "decline_reason": null,
             "extra_data": {}
         },
         "subscription": {
             "id": "m5lwrskt18r4f",
             "created_at": "1468577492",
             "active": true,
             "cancelled_at": null,
             "current_period_start": 1468577492,
             "current_period_end": 1471169492,
             "card": {
                 "id": "mzivhql5yi9rf",
                 "customer": {
                     "id": "mhtaqdb4edvrf"
                 }
             },
             "plan": {
                 "id": "mcn15j2hwhq4f"
             },
             "extra_data": {}
         }
     }
}

Recurring payment failed

Event name: recurring_payment_failed

This notification is sent when a recurring payment fails.

Sample notification:
{
     "event": "recurring_payment_failed",
     "data": {
         "transaction": {
             "id": "f9g63mazh1wi1",
             "created_at": 1470238921,
             "amount": 2000,
             "currency": "usd",
             "authorized": false,
             "captured": false,
             "refunded": false,
             "captures": [],
             "refunds": [],
             "card": {
                 "id": "mzivhql5yi9rf",
                 "customer": {
                     "id": "mhtaqdb4edvrf"
                 }
             },
             "decline_reason": {
                 "code": 1001,
                 "description": "General decline"
             },
             "extra_data": {}
         },
         "subscription": {
             "id": "m5lwrskt18r4f",
             "created_at": "1468577492",
             "active": true,
             "cancelled_at": null,
             "current_period_start": 1468577492,
             "current_period_end": 1471169492,
             "card": {
                 "id": "mzivhql5yi9rf",
                 "customer": {
                     "id": "mhtaqdb4edvrf"
                 }
             },
             "plan": {
                 "id": "mcn15j2hwhq4f"
             },
             "extra_data": {}
         }
     }
}