API Reference

Introduction

Authentication

API requests authentication is made via HTTP Basic Auth. You have to send an API key as HTTP password, and the user field should 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

200 Request was validated and performed with success / Transaction succeed
400 Usually indicates bad/malformed request data
402 Related to payments - indicates failure
409 Indicates conflict - e.g. when you're trying to make multiple transactions on one card at the same time

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

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.

Test card numbers

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 subscription notifications webhook. For the rest of test cards, subscriptions will be billed according to their plan.
378282246310005 American Express
371449635398431 American Express

Test 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

2018-04-24

- Added description of HTTP status 409 to HTTP response codes.
- Added start_date optional attribute to be set on subscriptions.

2018-04-19

Added verification_transaction object to cards.

2018-04-04

Extended response for Create a subscription with a card for a given customer and Create a subscription with a card and a customer endpoints:
- return any transaction objects created during subscription creation attempt
- return card and customer objects, if created, even on failed subscription creation attempt

2018-03-27

Added Card transaction chargeback notification section.

2018-02-16

Added Create a subscription with a card for a given customer section.

2018-02-15

Extended cancellation_source values list.

2018-01-16

Added cancellation_source object to subscriptions.

2018-01-12

Added:
- Create a transaction with a card using CryptKey section.
- Create a card using CryptKey section.
Changed CryptKeys usage.

2017-09-13

Added decline_reason attribute to transactions.

2017-07-27

Added reference 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

Transaction object attributes

id
string
Transaction ID
RO
created_at
integer
Timestamp of a transaction creation
RO
amount
integer
required
Transaction amount
currency
string
required
Transaction currency
authorized
boolean
Indicates if a transaction was successfully authorized
RO
captured
boolean
Indicates if a transaction was fully captured
RO
captures
list
List of capture objects performed within a transaction
RO
refunded
boolean
Indicates if a transaction was fully refunded
RO
refunds
list
List of refunds objects performed within a transaction
RO
chargeback
object
Chargeback object, if reported
RO
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
RO
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
Additional information for declined transactions is provided in the 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/:card_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/:customer_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": "4444444444444448",
    "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": "444444",
    "num_last_4": "4448",
    "expiry_month": 11,
    "expiry_year": 2018,
    "origin_ipaddr": "91.17.133.219",
    "customer": {
      "id": "mhtaqdb4edvrf"
    },
    "extra_data": {}
  },
  "decline_reason": null,
  "extra_data": {}
}

Create a transaction with a card using CryptKey

The purpose of this method is to perform a transaction by sending sensitive data directly from mobile application or website front end code, so no card data will hit your servers, which results in improved security and fewer PCI compliance requirements.

By performing the steps below you will register a card and perform a $9.99 transaction on it.

1. Create CryptKey with v1.transactions.create_with_card permission

It has to be done from your application backend, and the request has to be authorized by an APIKey with the correct permission. Transaction details has to be sent along with create CryptKey request. Since this method is always executed within customer context, you have to also include customer_id in request payload. Sample request:
{
  "permission": "v1.transactions.create_with_card",
  "customer_id": "auIj01kcj98lfq",
  "transaction": {
    "amount": 999,
    "currency": "usd",
    "reference": "b138bc50148440ee",
    "extra_data": {
      "key": "value"
    }
  }
}
reference and extra_data are optional.

2. Pass CryptKey into your frontend code

The preferred method to achieve this would be to send request to your backend. But you could include the CryptKey value somewhere in your HTML code.

3. Encrypt the card data and send it directly to Straal API
POSThttps://api.straal.com/v1/encrypted
Request containing card data should have a following format:
{
  "name": "John Smith",
  "number": "4444444444444448",
  "cvv": "123",
  "expiry_month": 11,
  "expiry_year": 2018
}

Response body will contain only request_id which should be matched with request_finished notification.
{
  "request_id": "db7a6a7c37c949f78acb563427456ee3"
}
You can let your user know immediately if the payment succeeded by checking HTTP response code.

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": "4444444444444448",
    "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": "444444",
    "num_last_4": "4448",
    "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/:bank_account_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/:transaction_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/:customer_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/:card_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/:bank_account_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/:subscription_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.

Refund object attributes

id
string
Refund ID
RO
created_at
integer
Timestamp of refund creation
RO
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/:transaction_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/:transaction_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.

Card object attributes

id
string
Card object ID
RO
created_at
integer
Timestamp of object creation
RO
brand
string
Credit card brand
RO
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)
RO
num_last_4
string
Last 4 digits of card number (based on posted number)
RO
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 the request is sent from your back end
RO
customer
object
Credit card owner
EXPANDABLE
extra_data
object
Additional information about a card
verification_transaction
object
Object sent to override default verification transaction amount settings
POST ONLY
To ensure that the given credit card data is valid, we perform a verification_transaction when handling card object creation requests. By default, during card verification we authorize and void a small amount from the given credit card. Default amount and currency is configured during integration phase. To override default verification transaction amount settings, you have to send verification_transaction object in create card request.

Verification transaction object attributes

amount
integer
Verification transaction amount
currency
string
Verification transaction currency

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": "4444444444444448",
  "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": "444444",
  "num_last_4": "4448",
  "expiry_month": 11,
  "expiry_year": 2018,
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "id": "mbrudb30nt9rf"
  },
  "extra_data": {}
}

Create a card using CryptKey

The purpose of this method is to create a card directly from mobile application or website front end code, so no card data will hit your servers, which results in improved security and fewer PCI compliance requirements.

1. Create CryptKey with v1.cards.create permission

It has to be done from your application backend, and the request has to be authorized by an APIKey with the correct permission. Since this method is always executed within customer context, you have to also include customer_id in request payload. Sample request:
{
  "permission": "v1.cards.create",
  "customer_id": "auIj01kcj98lfq",
  "card": {
    "extra_data": {
      "key": "value"
    }
  }
}
extra_data parameter of card is optional and since it's the only possible attribute of card, you don't have to include card object at all.

2. Pass CryptKey into your frontend code

The preferred method to achieve this would be to send request to your backend. But you could include the CryptKey value somewhere in your HTML code.

3. Encrypt the card data and send it directly to Straal API
POSThttps://api.straal.com/v1/encrypted
Example request payload containing card data:
{
  "name": "John Smith",
  "number": "4444444444444448",
  "cvv": "123",
  "expiry_month": 11,
  "expiry_year": 2018
}
Response body will contain only request_id which should be matched with request_finished notification.
{
  "request_id": "db7a6a7c37c949f78acb563427456ee3"
}
You can let your user know immediately if payment succeeded by checking HTTP response code.

Create a card with a customer

POSThttps://api.straal.com/v1/cards
v1.cards.create_with_customer
Sample request:
{
  "name": "John Smith",
  "number": "4444444444444448",
  "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": "444444",
  "num_last_4": "4448",
  "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/:card_id
v1.cards.get
Sample response:
{
  "id": "mzivhql5yi9rf",
  "created_at": 1467906605,
  "brand": "visa",
  "name": "John Smith",
  "num_bin": "444444",
  "num_last_4": "4448",
  "expiry_month": 11,
  "expiry_year": 2018,
  "origin_ipaddr": "91.17.133.219",
  "customer": {
    "id": "mbrudb30nt9rf"
  },
  "extra_data": {}
}

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": "444444",
        "num_last_4": "4448",
        "expiry_month": 10,
        "expiry_year": 2016,
        "origin_ipaddr": "123.10.11.12",
        "customer": {
          "id": "bq75z9dhfut5k"
        },
        "extra_data": {}
      },
      {
        "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"
        },
        "extra_data": {}
      },
      {
        "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"
        },
        "extra_data": {}
      }
  ],
  "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/:customer_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": "444444",
        "num_last_4": "4448",
        "expiry_month": 10,
        "expiry_year": 2016,
        "origin_ipaddr": "123.10.11.12",
        "extra_data": {}
      },
      {
        "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",
        "extra_data": {}
      }
  ],
  "page": 1,
  "per_page": 3,
  "total_count": 2
}

Bank Accounts

Bank account can be used to perform SEPA Direct Debit transactions.

Bank account object attributes

id
string
Bank account object ID
RO
created_at
integer
Timestamp of object creation
RO
name
string
required
Bank account holder name
iban
string
required
The International Bank Account Number
bic
string
The Business Identifier Code
mandate_id
string
ID of mandate created for bank account object
RO
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/:bank_account_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 bank accounts for the specified customer ID.
GEThttps://api.straal.com/v1/customers/:customer_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.

Customer objects

id
string
Customer object ID
RO
created_at
integer
Timestamp of object creation
RO
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/:customer_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, that is, a card or a bank account.

Subscription object attributes

id
string
Subscription object ID
RO
created_at
integer
Timestamp of object creation
RO
current_period_start
integer
-
RO
current_period_end
integer
-
RO
active
boolean
Indicates if subscription is active
cancelled_at
integer
Cancellation timestamp
RO
cancellation_source
object
The code and description of the cancellation reason (see the table below)
RO
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
start_date
date
If set, the first subscription period, or trial, will be calculated starting from this future date.
Allowed data types: timestamp or ISO formatted date ("YYYY-MM-DD")

Available cancellation_source codes

1
API request
2
Antifraud rules
5
Received a fraud response for a transaction
6
Fraud reported
7
Chargeback
8
Credit card expired

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/:card_id/subscriptions
v1.subscriptions.create
Sample request:
{
  "plan_id": "mcn15j2hwhq4f"
}
Sample response:
{
  "id": "m5lwrskt18r4f",
  "created_at": 1468577492,
  "active": true,
  "cancelled_at": null,
  "cancellation_source": 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.
- created card and customer objects are added to response when an error occurs during subscription creation. You can use these objects in other views.
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,
  "cancellation_source": 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"
    },
    "extra_data": {},
    "transactions": [
      {
        "amount": 100,
        "authorized": true,
        "captured": false,
        "captures": [],
        "chargeback": null,
        "created_at": 1468577590,
        "currency": "usd",
        "decline_reason": null,
        "extra_data": {},
        "id": "n4lar14f3a54f",
        "reference": null,
        "refunded": false,
        "refunds": []
      }
    ]
  },
  "plan": {
    "id": "mcn15j2hwhq4f"
  },
  "extra_data": {},
  "straal_custom_data": {}
}
Sample error response:
{
  "errors": [
    {
      "message": "Authorization failed",
      "code": 60001
    }
  ],
  "plan": {
    "id": "cwssdg3d951dt",
  },
  "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": 1522238802,
      "email": "customer@email.com",
      "reference": "7459320801"
    },
    "extra_data": {},
    "transactions": [
      {
        "amount": 100,
        "authorized": false,
        "captured": false,
        "captures": [],
        "chargeback": null,
        "created_at": 1468577590,
        "currency": "usd",
        "decline_reason": {
          "code": 1001,
          "description": "General decline",
        },
        "extra_data": {},
        "id": "n4lar14f3a54f",
        "reference": null,
        "refunded": false,
        "refunds": []
      }
    ],
  },
  "extra_data": {}
}

Create a subscription with a card for a given customer

Creates a subscription for a specified customer ID. You can use this method multiple times to create additional subscriptions for one customer using different cards. 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 object is 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. - created card object is added to response when an error occurs during subscription creation. You can use this object in other views.
POSThttps://api.straal.com/v1/customers/:customer_id/subscriptions
v1.subscriptions.create_for_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",
  }
}
Sample response:
{
  "id": "m5lwrskt18r4f",
  "created_at": 1468577492,
  "active": true,
  "cancelled_at": null,
  "cancellation_source": 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"
    },
    "extra_data": {},
    "transactions": [
      {
        "amount": 100,
        "authorized": true,
        "captured": false,
        "captures": [],
        "chargeback": null,
        "created_at": 1468577590,
        "currency": "usd",
        "decline_reason": null,
        "extra_data": {},
        "id": "n4lar14f3a54f",
        "reference": null,
        "refunded": false,
        "refunds": []
      }
    ]
  },
  "plan": {
    "id": "mcn15j2hwhq4f"
  },
  "extra_data": {},
  "straal_custom_data": {}
}
Sample error response:
{
  "errors": [
    {
      "message": "Authorization failed",
      "code": 60001
    }
  ],
  "plan": {
    "id": "cwssdg3d951dt",
  },
  "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",
    },
    "extra_data": {},
    "transactions": [
      {
        "amount": 100,
        "authorized": false,
        "captured": false,
        "captures": [],
        "chargeback": null,
        "created_at": 1468577590,
        "currency": "usd",
        "decline_reason": {
          "code": 1001,
          "description": "General decline",
        },
        "extra_data": {},
        "id": "n4lar14f3a54f",
        "reference": null,
        "refunded": false,
        "refunds": []
      }
    ],
  },
  "extra_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/:bank_account_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,
  "cancellation_source": 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/:subscription_id
v1.subscriptions.get
Sample response:
{
  "id": "m5lwrskt18r4f",
  "created_at": 1468577492,
  "active": true,
  "cancelled_at": null,
  "cancellation_source": 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,
      "cancellation_source": 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,
      "cancellation_source": 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/:customer_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,
      "cancellation_source": 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/:card_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,
      "cancellation_source": 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/:subscription_id/cancel
v1.subscriptions.cancel
Sample response:
{
  "id": "m5lwrskt18r4f",
  "created_at": 1468577492,
  "active": false,
  "cancelled_at": 1488214269,
  "cancellation_source": {
    "code": 1,
    "description": "API request"
  },
  "current_period_start": 1468577492,
  "current_period_end": 1471169492,
  "card": {
    "id": "mru196faf8r4f",
    "customer": {
      "id": "mj3mg7w3w8r4f"
    }
  },
  "plan": {
    "id": "mcn15j2hwhq4f"
  },
  "extra_data": {},
  "straal_custom_data": {}
}

Plans

Plan defines how often and what amount will be taken off customer's account during subscription lifetime.

Plan object attributes

id
string
Plan object ID
RO
created_at
integer
Timestamp of object creation
RO
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
Either "day", "month"` or "year"
step_value
integer
required
How many of step_type make a billing period

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
}

Checkout Page

Checkout Page is commonly used and popular choice for accepting payments online. This method will minimize the amount of work that has to be done in order to integrate with Straal.

In order to initialize new payment via Checkout Page you have to initialize checkout page and redirect user to received checkout_url. Straal will send notification to your backend about payment status.

Checkout object attributes

id
string
Checkout object ID
RO
created_at
integer
Timestamp of object creation
RO
currency
string
required
Transaction currency
amount
integer
required
Transaction amount
ttl
integer
required
Checkout expiration time (in seconds)
MINVAL:60MAXVAL:1200
success_url
string
required
User will be redirected to this URL after successful payment
failure_url
string
required
User will be redirected to this URL after failed payment
order_description
string
Description of an order - this information will be visible on checkout page form
order_reference
string
Reference of an related order - this information will be visible on checkout page form
checkout_url
string
URL of checkout page, you should redirect your user to this address
RO
attempts
list
List of user attempts
RO

Initialize checkout

POSThttps://api.straal.com/v1/customers/:customer_id/checkouts
v1.checkouts.create
Sample request:
{
  "currency": "usd",
  "amount": 1999,
  "ttl": 600,
  "success_url": "https://yourproduct.com/payment_succeed.html",
  "failure_url": "https://yourproduct.com/payment_failed.html",
  "order_description": "Star Wars mug XXL",
  "order_reference": "26906303414c4f2782c653e0501c13b1"
}
Sample response:
{
  "id": "a9szcp9u9e8n3",
  "created_at": 1519841724,
  "amount": 1999,
  "currency": "usd",
  "ttl": 600,
  "attempts": [],
  "checkout_url": "https://checkout.straal.com/9ad38808ebbc7be00e74b86bc28542",
  "success_url": "https://yourproduct.com/payment_succeed.html",
  "failure_url": "https://yourproduct.com/payment_failed.html",
  "order_description": "Star Wars mug XXL",
  "order_reference": "26906303414c4f2782c653e0501c13b1"
}

Get checkout object

GEThttps://api.straal.com/v1/checkouts/:checkout_id
v1.checkouts.get
Sample response:
{
  "id": "a9szcp9u9e8n3",
  "created_at": 1519841724,
  "amount": 1999,
  "currency": "usd",
  "ttl": 600,
  "attempts": [],
  "checkout_url": "https://checkout.straal.com/9ad38808ebbc7be00e74b86bc28542",
  "success_url": "https://yourproduct.com/payment_succeed.html",
  "failure_url": "https://yourproduct.com/payment_failed.html",
  "order_description": "Star Wars mug XXL",
  "order_reference": "26906303414c4f2782c653e0501c13b1",
  "customer": {
    "id": "qv9dpoblsbunc"
  },
  "attempts": [
    {
      "id": "ygydpuy77bsnv",
      "created_at": 1519841764,
      "status": "succeeded",
      "transaction": {
        "id": "u25mpvzysb9nm",
        "created_at": 1519841765,
        "reference": null,
        "amount": 1999,
        "currency": "usd",
        "decline_reason": null,
        "authorized": true,
        "captured": true,
        "captures": [
          {
            "id": "52jcsp07sbpnu",
            "created_at": 1519841768,
            "amount": 1999
          }
        ],
        "card": {
          "id": "ydpjpudy6bsn5",
          "created_at": 1519841765,
          "name": "Harry Potter",
          "num_bin": "444444",
          "num_last_4": "4448",
          "expiry_month": 10,
          "expiry_year": 2021,
          "brand": "visa",
          "origin_ipaddr": "94.113.114.115",
          "extra_data": {}
        },
        "refunded": false,
        "refunds": [],
        "chargeback": null,
        "extra_data": {}
      }
    }
  ]
}

CryptKeys

CryptKey is a special object that allows you to send encrypted data directly to our API endpoint without needing to authorize using API Key. This can be useful in various scenarios, such as making a request from mobile or web applications where you can't expose the API Key. 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.

CryptKey object attributes

id
string
Card object ID
RO
created_at
integer
Timestamp of object creation
RO
key
string
Actual key which will be used to encrypt data
RO
ttl
integer
Key expiration time (in seconds)
RO
permission
string
required
Valid request permission string

Create a CryptKey

A request for creating CryptKey has to be authorized by an API Key. 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",
  "customer_id": "mzivhql5yi9rf"
}
Sample response (key attribute is shortened):
{
  "id": "70xfzmynzgkih",
  "created_at": 1470302857,
  "key": "06c5fbc1a9800003ba(...)",
  "permission": "v1.cards.create",
  "ttl": 600
}

Usage

Every request encrypted with CryptKey should be sent to special endpoint:
POSThttps://api.straal.com/v1/encrypted
Read more detailed usage examples:
- Create a transaction with a card using CryptKey
- Create a card using CryptKey

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.

CSR object attributes

id
string
CSR ID
RO
created_at
integer
Timestamp of CSR object creation
RO
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/:csr_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
}

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: sepa_transaction_chargeback

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

Sample notification:
{
  "event": "sepa_transaction_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
  }
}

Transactions

Card transaction chargeback

Event name: card_transaction_chargeback

This notification is sent when a credit card transaction is charged back.

Sample notification:
{
  "event": "card_transaction_chargeback",
  "data": {
    "transaction": {
      "id": "pzhazstgsj497",
      "created_at": 1521729203,
      "amount": 999,
      "currency": "usd",
      "authorized": true,
      "captured": true,
      "refunded": false,
      "captures": [
        {
          "id": "s2xcew6gsj79p"
        }
      ],
      "refunds": [],
      "card": {
        "id": "pzhazstgsj497",
          "customer": {
            "id": "s713n8vgsj79p"
          }
      },
      "chargeback": {
        "id": "zy8clu5y8bzve",
        "effective_date": 1577923200,
        "reason_code": "62",
        "reason_description": "Counterfeit Transaction",
        "arn": "12345678901234567890123"
      },
      "reference": "ieph3wow3Hooch4b",
      "decline_reason": null,
      "extra_data": {}
    },
    "timestamp": 1577934248
  }
}

Subscriptions

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,
             "cancellation_source": 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,
             "cancellation_source": null,
             "current_period_start": 1468577492,
             "current_period_end": 1471169492,
             "card": {
                 "id": "mzivhql5yi9rf",
                 "customer": {
                     "id": "mhtaqdb4edvrf"
                 }
             },
             "plan": {
                 "id": "mcn15j2hwhq4f"
             },
             "extra_data": {}
         }
     }
}

Subscription cancelled

Event name: subscription_cancelled

This notification is sent when a subscription is cancelled.

Sample notification:
{
    "event": "subscription_cancelled",
    "data": {
        "subscription": {
            "id": "m5lwrskt18r4f",
            "created_at": 1468577492,
            "active": false,
            "cancelled_at": 1468671650,
            "cancellation_source": {
                "code": 1,
                "description": "API request"
            },
            "current_period_start": 1468577492,
            "current_period_end": 1471169492,
            "card": {
                "id": "mzivhql5yi9rf",
                "customer": {
                    "id": "mhtaqdb4edvrf"
                }
            },
            "plan": {
                 "id": "mcn15j2hwhq4f"
             },
             "extra_data": {},
             "straal_custom_data": {}
        }
    }
}