# 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.
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
You send us the card details via API, checkout page or a payment form.
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.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.
# 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 | Declined by issuing bank | 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. |
1016 | Antifraud decline | Transaction declined by Straal's antifraud system. |
1017 | Risk blocked in external payment system | Transaction declined by Acquirer's antifraud system. |
1018 | Authentication 3DS failed | Client not successfully authorized during 3DS process. |
1019 | SCA required | Additional customer authentication required. |
1020 | Issuer not available | The acquirer was unable to complete the transaction on the issuer’s side - try again later. Note that withdrawal limits may still apply. |
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. |
2000 | Transaction declined | General transaction decline. Please contact support for more information. |