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

Use cases

Use case: a monthly subscription

This scenario fits perfectly to an online service provider, such as music or video streaming sites. A new customer decides to subscribe to your service for a monthly fee of $9.99. As a newcomer, they get a free 30-day trial.

Prerequisite

To add a new subscription, there needs to be a plan created beforehand. In this example it’s a monthly transaction for $9.99 with a 30-day trial. If you haven't yet, you need to create it. You will need to specify:
- your plan's name
- the amount to be charged, e.g. (999) for 9.99
- currency
- trial length in days (here: 30)
- how often the card will be charged (once every month)

Creating a subscription

A subscription needs to be connected to a customer and a card. The easiest way to do this is to create them all at once. To do so, you will need:
- your plan's ID generated at its creation (plan_id)
- credit or debit card details
- the customer's email address
- (optionally) your unique reference for this customer

If you successfully created a new subscription, the server response will provide you with its details.
If you wish to check the details of your new subscription later, you can do so using its ID.

Use case: a one-click transaction

This scenario fits a returning customer of an online retailer or a mobile app store. Such a customer might perform irregular transactions of varying amounts. A one-click payment is generally a convenience for such a customer.
When attempting the first payment, the customer is required to provide their card's security details. Once a card object has been created, it can later be referred to with its id, without the need to provide the card's CVV and expiration date each time.

Prerequisite

If you haven't yet, you need to create a customer first. You will need to specify the customer's email and (optionally) their unique reference. If you prefer not to create a customer separately, it's also possible to create a customer and a card along with the first transaction.

First transaction

During the first transaction a new customer needs to specify their card details, i.e. its number, CVV, expiry date and the cardholder's name. Additionally, Straal collects the IP address from which the card was created.
To find out more about the first transaction, see: creating a transaction with a card.

Further transactions

If a customer attempts a second or further transaction, they don't need to provide their card's security details. When a card object is created at the first transaction, the card's information is tokenized, so it can be substituted with its id afterwards. You can see an example in: creating a transaction.

Glossary

Card

An object which represents a credit card. When you create a new card object, Straal requires the card number, CVV number and expiry date. To create a card object in Straal, you need a card with a valid number and an expiry date in the future. The server response will contain the card's unique ID (a 13-character alphanumeric string), which you can use as a token in recurring transactions.

Card Authorization

Approval of the customer's payment. It's the first stage of the payment processing, and it's done in order to check if a card can be used in a transaction. While the funds aren't transferred immediately, they are "reserved" for a specific merchant. The funds are deducted from the customer's account when their financial institution receives a capture request from the merchant (see: Authorization Capture).

Authorization Capture

The second stage in the payment processing. After a financial institution successfully verifies the card, and receives a capture request from the merchant, the transaction is captured, i.e. funds can be transferred to the merchant's account. Depending on your setup, an authorization capture can take place automatically, or manually. Each manual capture needs to be confirmed by the merchant with a request to Straal API. In such case the merchant gains the ability to send a capture request when it's convenient for them, e.g. when their product has been shipped.

Chargeback

Return of funds to the cardholder - it reverses the payment. It's initiated by the Cardholder and can be performed by the cardholder's bank to reimburse the funds transferred from the cardholder's bank account or credit card. Depending on your bank and credit card issuer, a chargeback might result in a financial fee.

Customer

The merchant's client, e.g. the shopper. This object corresponds to a customer in the merchant's service (e.g. an online shop). Besides a unique id generated by the Straal API, it also accepts a reference object where you can store your unique reference. Retaining a customer object allows viewing summaries and statistics per customer, i.e. their subscriptions, cards, Life-Time Value etc. Storing this object correctly will make it easy to use the Straal Dashboard's features.

Merchant

A shop or a service provider that accepts and processes debit and credit card transactions, SEPA, Pay-By-Link, etc.

Refund

Return of funds to the customer, initiated by the merchant. It's possible to perform multiple refunds for one transaction. However, they can't exceed the total amount of the original transaction. Used e.g. when the merchant decides to return only a part of what has been paid by the customer.

SEPA

Single Euro Payments Area payment — a simplified bank transfer in EUR, made between entities based in EU countries. For the list of countries, visit The European Payments Council.

Subscription

An object representing a recurring billing. It requires the merchant to get the cardholder’s permission once in advance, then continues until the cardholder withdraws permission. A subscription has to be linked to a specific plan and either to a card or a bank account. It makes recurring transactions possible, but their frequency is defined by a plan.

Subscription plan

Configures subscriptions. It defines how often and what amount will be taken off customer's account during the subscription's lifetime.

Transaction

A set of operations for a card or a bank account. It's initialized by an authorization. A transaction consists of various operations, such as captures or refunds, and collects information about them in one object.

Verification Authorization

A payment to enable the merchant to verify if the card provided is active and linked to an account with funds. A minimal amount is authorized (i.e. reserved for payment). Then, you have a few choices:
- request an authorization capture — the funds are transferred to your account, and then you will make a refund
- cancel the authorization (depends on your setup)
- do nothing — the amount will be unblocked automatically (the waiting period may vary between banks)
A Verification Authorization is often done when creating a new subscription with a trial. First, a Verification Authorization takes place, and after the trial is over the customer is charged according to plan.