Transactions

Overview

With Straal you can perform online transactions the way you want, easily and securely. This section discusses operations that can be part of a transaction in Straal.

The image shows a diagram with the steps of a transaction, which is described below.

A transaction can start with tokenization when sending full card details. Then, an authorization takes place, followed by a capture. Additionally, an authorization can be cancelled, or voided, generally within the following 24 hours. In such case a capture doesn't take place. This option is not always available, so you should ask your Account Manager. Alternatively, a capture can be refunded.

In this section you will learn about:

  • Tokenization
  • Authorizations and capture requests
  • Refunds

Tokenization

During the first transaction with a particular card, Straal requires a complete set of card details. Card details include the cardholder name, full card number, CVV/CVC and expiry date.

The card then receives an ID, which you can store as a token (for example, for subsequent transactions) instead of keeping the sensitive data in your system. This process is called tokenization.

Straal uses tokenization when processing payment data in one-click and recurring transactions.

Some reasons why we use tokenization
  • Thanks to tokenization your system does not operate on full credit card data (such as its number and CVV/CVC), thus less demanding PCI-DSS Compliance requirements apply to your infrastructure. Read more in PCI Compliance.
  • If you use tokens, in the event of data breach, the attacker doesn't get access to sensitive card details.
  • If you store only tokens, you have less data to look after. It makes it easier to develop and maintain your application.
How tokenization happens
  1. You send us the card details via API, checkout page or a payment form.

  2. You receive the card ID (the card object), which acts as a token, that is, it can be used in recurring transactions instead of the sensitive data.

  3. We store card and cardholder data in a secure system, which is compliant with PCI-DSS requirements, so that you don't have to worry about it.

Authorizations and capture requests

A card authorization is the verification step of the payment.

It's the first stage of the payment processing, and it's done to verify if the card details are correct, if the cardholder has enough funds on their account to cover a specific transaction, and if their card is reported as stolen or lost. While the funds aren't transferred immediately, they appear as "blocked" on the cardholder’s account.

A card capture is the second stage in the processing of a transaction.

After the relevant financial institution successfully verifies the card, and the issuer bank receives a capture request, the funds are transferred from the cardholder account. Straal sends capture requests as soon as the card is successfully verified.

Currently, Straal handles authorizations and captures together as parts of a transaction. You can use the Straal API to create transactions for a new or existing (1) card, (2) card and customer, or (3) an existing bank account. In this example, you'll see how to create a transaction and add a card for an existing customer.

Use case – creating a transaction

To create a transaction you'll need:

  • the customer ID (see APIref: Create a customer)
  • the amount charged, expressed in the currency's smallest unit (cents, pence, and so on.), for example £42 would be 4200
  • the card details

You'll find an example request body for this case below. The transaction is made for £42 (sent as 4200). You'll send a POST request to Straal API endpoint /customers/:id/transactions where :id needs to be substituted with the ID of the customer your transaction is referring to.

Sample request body:

{
  "amount": 4200,
  "currency": "gbp",
  "reference": "b138bc50148440ee",
  "card": {
    "name": "Ford Prefect",
    "number": "4111111111111111",
    "cvv": "123",
    "expiry_month": 11,
    "expiry_year": 2022,
    "origin_ipaddr": "91.17.133.219"
  }
}

For a sample response and technical details of creating a transaction with a card, see: APIref: Creating a transaction with a card.

If you'd like to learn about different ways of creating a transaction, see APIref: Transactions.

Refunds

Unfortunately, it's sometimes necessary to return some or all the money to your customer. We understand it needs to be done as flawlessly as possible. Below you can see how easy it is to perform a partial or a full refund with Straal.

Use case – making a refund

To better understand the workflow of refunds, consider the following example.

A shopper of your online bookshop orders a copy of "The Hitchhiker's Guide to the Galaxy". A few days later, the courier arrives with a cardboard box. However, as the excited shopper opens it, they notice that the book is a little damaged at the edges – not a brand new one, as has been offered online.

Fortunately for you, instead of writing an angry review on social media, they reach out to let you know not everything went according to their expectations. In accordance with your returns policy, you decide to accept the return of the book and refund the transaction.

To perform a refund you'll need the ID of the transaction you'd like to refund.

You'll find an example request body for this case below. A refund request is sent to Straal API endpoint /transactions/:id/refund where :id needs to be substituted with the ID of the transaction your refund is referring to.

Sample request body:

{
  "extra_data": {
    "reason": "cancellation"
  }
}

For a sample response and technical details of doing a full refund, see: APIref: Creating a full refund.

If instead your customer would like to keep the book and receive a partial refund as a discount, you can perform a partial refund. To learn how to do it, see APIref: Creating a partial refund.


What you can do next:


Remember you can consult our comprehensive API Reference at any moment.

For help with payments vocabulary, head to our glossary.

You can reach us by e-mail. IT Support: [email protected], Support Team: [email protected].

Authorization decline codes

A vast majority of transactions are successful. Payments are occasionally declined though, which can be caused by various factors. In this section, we present the possible reasons for the rejection of transactions and our recommendations as to what should be done in order to ensure payment success in the future.

The most common reasons for the rejection of card transactions include:

  • Insufficient funds in the customer’s account to execute the payment
  • Inadequate card settings –  the maximum transfer limit is too low or the card is blocked for online and mobile transactions
  • Incorrect card number or invalid card (past the expiry date)
  • Refusal from the issuing bank due to its antifraud policy

In most cases it is the bank that can provide the specific reason for the rejection. Straal’s recommendation is therefore for the payer to contact their bank and verify the underlying cause of the payment decline.

The table below presents the possible card decline codes in the Straal system and suggestions regarding the message that should be forwarded to the user.

Code Description Information for merchant
1001 General decline Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings.
1002 Insufficient funds Transaction declined by card issuer - insufficient funds or limit exceeded. Please, ask the cardholder to contact their bank and check card settings.
1003 Expired card Transaction declined by card issuer - expired card. Please, ask the cardholder to use a valid card.
1004 Internal error An error has occured on the side of Straal. Please, contact Straal for more information and support.
1005 Invalid amount Transaction declined by card issuer - insufficient funds or limit exceeded. Please, ask the cardholder to contact their bank and check card settings.
1006 Invalid card data Transaction declined by card issuer - invalid card details.
1007 Restricted card Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings.
1008 Invalid transaction Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings.
1009 Withdrawal limit exceeded Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings.
1010 Card not supported Transaction declined by card issuer - card type not supported.
1011 Transaction not permitted to cardholder Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings.
1012 Merchant account error Your merchant account is misconfigured. Please, contact Straal - [email protected]
1013 Security violation Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings.
1014 Gateway frequency limit exceeded Transaction declined by card issuer. Please, ask the cardholder to contact their bank and check card settings.
1015 Acquirer error An error has occured on the side of the acquiring bank. Please, contact Straal.
1101 Possible fraud Transaction declined by card issuer. WARNING! The card has been designated as lost or stolen. DO NOT MAKE ANY FURTHER CHARGING ATTEMPTS - THOSE MIGHT BE CONSIDERED AS FRAUDULENT.